Query API

API for faceted querying of metadata documents.

Not a complete implementation of but conform to the following OASIS standards:

[OData-Part2]
OData Version 4.0. Part 2: URL Conventions Plus Errata 03. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. 02 June 2016. OASIS Standard incorporating Approved Errata 03.
[OData-JSON-Format-v4.0]
OData JSON Format Version 4.0 Plus Errata 03. Edited by Ralf Handl, Michael Pizzo, and Mark Biamonte. 02 June 2016. OASIS Standard incorporating Approved Errata 03.
Contents

Response Format

Example: /query/a5-2?pretty&$search=story&$count&$orderby=Title&$skip=10&$top=3&highlight&facets=Keywords,Country,ResourceType&autocomplete

{
  "@odata.context": "a5:/query/a5-2",
  "@odata.count": 41,
  "@odata.nextLink": "?$skip=13",
  "@a5.selector": {
    "repository": "a5-2",
    "$count": true,
    "$filter": null,
    "$orderby": {
      "Title": "asc"
    },
    "$search": "story",
    "$select": null,
    "$skip": 10,
    "$top": 3,
    "autocomplete": true,
    "drill": null,
    "facets": {
      "Keywords": 10,
      "Country": 10,
      "ResourceType": 10
    },
    "fields": null,
    "highlight": true,
    "pretty": true
  },
  "value": 
  [
    {
      "@a5.highlight": {
        "Description": 
        [
          "The session contains the audio track of a video recording of a folkloric <em>story<\/em> and its annotation",
          ".\nThe <em>story<\/em> was video recorded outside the kitchen building of the collector's neighbours in Vera'a village."
        ]
      },
      "@a5.orderby": 
      [
        "Multi-CAST Vera'a (as1 text, \"The Two Friends\")"
      ],
      "ProjectDisplayName": 
      [
        "Multi-CAST Vera'a"
      ],
      "Description": 
      [
        "The session contains the audio track of a video recording of a folkloric story and its annotation.\nThe story was video recorded outside the kitchen building of the collector's neighbours in Vera'a village.",
        "\"E ruwa mēn bulsalaruō\" (\"The Two Friends\")\n\nTwo friends seek a intra-sex pig, called 'raw' in Vera'a. They start out from the village of Lemerig, and come across the trickster spirit Dōl who has taken on the outer appearance of a human being. He sells them a 'raw' for a large sum of shell money, and other customary goods.\nThey spend the night at his place, having dinner and kava together before going to sleep. Dōl at night, when the two are asleep, ties up the penis of one of the friends.\nIn the morning they get up and take their leave, and on the way that one friend with the tied-up penis starts feeling unwell.\nThen the two come across a man - again Dōl who has again changed his outer appearance - who helps them 'heal the disease' by removing the vine that he tied up that one man's penis with. In return he demands the 'raw', which the two give to him before returning home without the 'raw' and bared of their money and other goods."
      ],
      "Keywords": 
      [
        "Discourse",
        "traditional narrative",
        "Unspecified",
        "non-interactive",
        "non-elicited",
        "Family",
        "Monologue"
      ],
      "accessLevel": "public",
      "Title": 
      [
        "Multi-CAST Vera'a (as1 text, \"The Two Friends\")"
      ],
      "Country": 
      [
        "Vanuatu"
      ],
      "Region": 
      [
        "Banks Island, Vanua Lava"
      ],
      "ResourceType": 
      [
        "audio"
      ],
      "id": 
      [
        "hdl:11341/00-0000-0000-0000-1CAE-5"
      ],
      "ProjectDescription": 
      [
        "The Multi-CAST Vera'a project is part of the Multi-CAST project.\nIt is based on a collection of recordings from the Oceanic language Vera'a that has approx. 450 speakers in the north of Vanuatu.\nThe Vera'a corpus was compiled first within a DoBeS project focussed on the documentation of the Vera'a language and the Vurës language, both spoken on the same island (2006-2012).\nWork on the Vera'a Multi-CAST collection was undertaken partly within this DoBeS project, and partly within Stefan Schnell's ARC-funded DECRA project \"Typology of Language Use\", hosted by La Trobe University, Melbourne."
      ],
      "ObjectLanguage": 
      [
        "Vera'a"
      ]
    },
    {
      "@a5.highlight": {
        "Description": 
        [
          "The session contains an audio recording together with its annotation of a <em>story<\/em> delivered",
          " the meat inside the fruit and shat into it.\nThe <em>story<\/em> concludes with eternal enmity between the two resulting from Rat's cheating on Cat."
        ]
      },
      "@a5.orderby": 
      [
        "Multi-CAST Vera'a (gabg text, \"The Cat and the Rat\")"
      ],
      "ProjectDisplayName": 
      [
        "Multi-CAST Vera'a"
      ],
      "Description": 
      [
        "The session contains an audio recording together with its annotation of a story delivered by the speaker - the host 'father' of the collector - in his kitchen.",
        "\"Buskat won gusuwō\" (\"The Cat and the Rat\")\n\nA fable in which Cat and Rat are friends living together in the same house. One day they go down to the sea fishing.\nThey catch lots of fish, scale and gut it, and then walk back up the shore to get some pawpaw from Cat's former garden.\nThe garden is pretty void of any ripe edible pawpaw fruit, but they find a single tree with one ripe fruit.\nThen they argue about who should be climbing for that fruit, and the result of the argument is that Rat climb.\nRat climbs up and, while Cat waits on the ground and cannot quite see what is going on top of the pawpaw tree. Rat takes the opportunity and climbs around the stalk, gnaws into the fruit, and eats it all out from outside. Cat gets impatient, starts climbing up, and finds that Rat has finished off the meat inside the fruit and shat into it.\nThe story concludes with eternal enmity between the two resulting from Rat's cheating on Cat."
      ],
      "Keywords": 
      [
        "Discourse",
        "traditional narrative",
        "Unspecified",
        "non-interactive",
        "non-elicited",
        "Family",
        "Monologue"
      ],
      "accessLevel": "public",
      "Title": 
      [
        "Multi-CAST Vera'a (gabg text, \"The Cat and the Rat\")"
      ],
      "Country": 
      [
        "Vanuatu"
      ],
      "Region": 
      [
        "Banks Island, Vanua Lava"
      ],
      "ResourceType": 
      [
        "audio"
      ],
      "id": 
      [
        "hdl:11341/00-0000-0000-0000-1CB5-6"
      ],
      "ProjectDescription": 
      [
        "The Multi-CAST Vera'a project is part of the Multi-CAST project.\nIt is based on a collection of recordings from the Oceanic language Vera'a that has approx. 450 speakers in the north of Vanuatu.\nThe Vera'a corpus was compiled first within a DoBeS project focussed on the documentation of the Vera'a language and the Vurës language, both spoken on the same island (2006-2012).\nWork on the Vera'a Multi-CAST collection was undertaken partly within this DoBeS project, and partly within Stefan Schnell's ARC-funded DECRA project \"Typology of Language Use\", hosted by La Trobe University, Melbourne."
      ],
      "ObjectLanguage": 
      [
        "Vera'a"
      ]
    },
    {
      "@a5.highlight": {
        "Description": 
        [
          "The session contains an audio recording together with its annotation of a <em>story<\/em> delivered"
        ]
      },
      "@a5.orderby": 
      [
        "Multi-CAST Vera'a (gaqg text, \"The Seagull and the Rat\")"
      ],
      "ProjectDisplayName": 
      [
        "Multi-CAST Vera'a"
      ],
      "Description": 
      [
        "The session contains an audio recording together with its annotation of a story delivered by the speaker - the host 'father' of the collector - in his kitchen.",
        "\"Qono won gusuwō\" (\"The Seagull and the Rat\")\n\nThis is a fable about Seagull, Rat and Turtle. Seagull and Rat meet and make friends. Seagull has his nest ontop of Rat's dwelling inside the trunk of a nanara tree.\nAt night, and despite Seagull's reassurance to the contrary, massive rain pours down and fills the dry creek in which the nanara trunk was sitting. The rising water takes the trunk out into the open sea, and in the morning Rat finds himself in the middle of the ocean.\nTurtle comes across underneath the trunk and rescues Rat on his back, taking him to the shore. But then Turtle gets caught and tied up by two humans who leave him there and report back to their village's chief about this miraculous find of protein containing food. Rat has run up into the bush.\nThe villagers prepare the cooking of the turtle, which is observed by Seagull. Seagull comes up with a plot to free Trutle:\nhe will decorate himself in customary dresses and perform a dance for the villagers. While the villagers are distracted by his dancing, Rat will rush down and gnaw open the vines that tie up Turtle.\nSo it goes, Turtle can flee back to the sea, and Rat rushes back into the bush, while Seagull gives a mocking speech to the villagers and flies off too."
      ],
      "Keywords": 
      [
        "Discourse",
        "traditional narrative",
        "Unspecified",
        "non-interactive",
        "non-elicited",
        "Family",
        "Monologue"
      ],
      "accessLevel": "public",
      "Title": 
      [
        "Multi-CAST Vera'a (gaqg text, \"The Seagull and the Rat\")"
      ],
      "Country": 
      [
        "Vanuatu"
      ],
      "Region": 
      [
        "Banks Island, Vanua Lava"
      ],
      "ResourceType": 
      [
        "audio"
      ],
      "id": 
      [
        "hdl:11341/00-0000-0000-0000-1CB6-B"
      ],
      "ProjectDescription": 
      [
        "The Multi-CAST Vera'a project is part of the Multi-CAST project.\nIt is based on a collection of recordings from the Oceanic language Vera'a that has approx. 450 speakers in the north of Vanuatu.\nThe Vera'a corpus was compiled first within a DoBeS project focussed on the documentation of the Vera'a language and the Vurës language, both spoken on the same island (2006-2012).\nWork on the Vera'a Multi-CAST collection was undertaken partly within this DoBeS project, and partly within Stefan Schnell's ARC-funded DECRA project \"Typology of Language Use\", hosted by La Trobe University, Melbourne."
      ],
      "ObjectLanguage": 
      [
        "Vera'a"
      ]
    }
  ],
  "@a5.facets": {
    "Keywords": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 70,
      "buckets": 
      [
        {
          "doc_count": 26,
          "key": "Unspecified"
        },
        {
          "doc_count": 17,
          "key": "Discourse"
        },
        {
          "doc_count": 12,
          "key": "Stimuli"
        },
        {
          "doc_count": 11,
          "key": "Monologue"
        },
        {
          "doc_count": 10,
          "key": "Family"
        },
        {
          "doc_count": 10,
          "key": "non-elicited"
        },
        {
          "doc_count": 9,
          "key": "non-interactive"
        },
        {
          "doc_count": 9,
          "key": "traditional narrative"
        },
        {
          "doc_count": 8,
          "key": "elicited"
        },
        {
          "doc_count": 8,
          "key": "interactive"
        }
      ]
    },
    "Country": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": 
      [
        {
          "doc_count": 24,
          "key": "Germany"
        },
        {
          "doc_count": 9,
          "key": "Vanuatu"
        },
        {
          "doc_count": 7,
          "key": "Bolivia"
        }
      ]
    },
    "ResourceType": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": 
      [
        {
          "doc_count": 36,
          "key": "audio"
        },
        {
          "doc_count": 23,
          "key": "video"
        }
      ]
    }
  },
  "@a5.autocomplete": {
    "autocomplete": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 48,
      "buckets": 
      [
        {
          "doc_count": 41,
          "key": "story"
        },
        {
          "doc_count": 13,
          "key": "story bawang"
        },
        {
          "doc_count": 13,
          "key": "story bawang kesuna"
        },
        {
          "doc_count": 11,
          "key": "story retelling"
        },
        {
          "doc_count": 8,
          "key": "story they"
        },
        {
          "doc_count": 7,
          "key": "story straight"
        },
        {
          "doc_count": 7,
          "key": "story straight language"
        },
        {
          "doc_count": 7,
          "key": "story they made"
        },
        {
          "doc_count": 7,
          "key": "story with"
        },
        {
          "doc_count": 7,
          "key": "story with the"
        }
      ]
    }
  }
}

Query Requests

Fulltext Search [$search]

GET {scheme}://{server}/query/{repository}?$search={querystring}

Matches a query string. Query strings follow the Lucene Syntax.

Example Description
/query/a5-1?$search=communication&pretty Searches for the term "communication" in repository "a5-1".
/query/a5-2?$search=*&pretty "*" matches all fulltext terms contained in repository "a5-2".
/query/a5-1?$search=audio OR video&pretty Matches all documents containing the fulltext terms "audio" or "video".
/query/a5-1?$search=audio AND video&pretty Matches all documents containing the fulltext terms "audio" and "video".
/query/a5-2?$search=audio NOT video&pretty Returns all documents matching "audio", but not "video".
/query/a5-2?$search=bali*&pretty Matches all fulltext terms starting with "bali*".
/query/a5-2?$search=*ish&pretty Matches all fulltext terms ending with "*ish".
/query/a5-2?$search='traditional narrative'&pretty Matches all documents containing the phrase "traditional narrative".

For more possibilities, see the official Lucene documentation.

Keyword Filtering [$filter]

GET {scheme}://{server}/query/{repository}?$filter={field1 (eq|ne|gt|ge|lt|le) "term1" (and|or|not) field2 ...}

In contrast to "$search", "$filter" evaluates exact matches on field values.

Example Description
/query/a5-1?pretty&$filter=id eq hdl:11341/00-0000-0000-0000-1BD6-5 Returns document with field "id" equals to "hdl:11341/00-0000-0000-0000-1BD6-5". No quotes are used here to enclose the term.
/query/a5-1?pretty&$filter=Format eq 'text/x-eaf%2Bxml' Returns all documents with field "Format" equals to "text/x-eaf+xml". Note that the plus sign "+" has to be encoded as "%2B".
/query/a5-1?pretty&$filter=Format ne 'text/x-eaf%2Bxml' Returns all documents with field "Format" not equals to "text/x-eaf+xml". Note that the plus sign "+" has to be encoded as "%2B".
/query/a5-1?pretty&$filter=Format ne text/x-eaf%2B or Format ne audio/x-wav Returns all documents with field "Format" not equals to "text/x-eaf+xml" or not equals to "audio/x-wav.
/query/a5-2?pretty&$filter=(ObjectLanguage eq Bali or ObjectLanguage eq German) and ResourceType eq audio Returns all documents with object language equals to "Bali" or "German" and resource type equals to "audio".

Counting Hits [$count]

GET {scheme}://{server}/query/{repository}?$count

Whether to include number of hits in the query result.

Example Description
/query/a5-1?$search=communication&$count&pretty Searches for "communication" in repositoy named "a5-1" and includes the number of hits in field "@odata.count".

Sorting Hits [$orderby]

GET {scheme}://{server}/query/{repository}?$orderby={field1 (asc|desc),field2 (asc|desc),...}

Sorts results according to specific fields in ascending or descending order.

Example Description
/query/a5-2?$search=*&$orderby=ProjectDisplayName&pretty Returns all documents of repository "a5-2" ordered by field "ProjectDisplayName" in default ascending order.
/query/a5-2?$search=*&$orderby=ProjectDisplayName asc&pretty Returns all documents of repository "a5-2" ordered by field "ProjectDisplayName" in ascending order.
/query/a5-2?$search=*&$orderby=ProjectDisplayName desc,Country asc&pretty Returns all documents of repository "a5-2" primarily ordered by field "ProjectDisplayName desc" (descending) and secondarily ordered by field "Country asc" (ascending).

Navigating Hits [$skip,$top]

GET {scheme}://{server}/query/{repository}?$skip={integer}&$top={integer}

Allows navigation of search results.

Example Description
/query/a5-1?$search=*&$skip=10&$top=30&pretty Example matches all documents contained in repository "a5-1". The first 10 results are skipped (skip=10). The number of results is 30 (top=30).
/query/a5-2?$search=communication&$skip=5&$top=1&pretty Example matches the term "communication" against repository a5-2. The first 5 results are skipped (skip=5). Only 1 item is returned (top=1).

Result Serialization [$select]

GET {scheme}://{server}/query/{repository}?$select={field1,field2,field3,...}

Defines which fields to include in the JSON result.

Example Description
/query/a5-2?$search=*&$select=id,ProjectDisplayName&pretty Returns all documents of repository "a5-2", but only fields "id", and "ProjectDisplayName".

Searching Selected Fulltext Fields [fields]

GET {scheme}://{server}/query/{repository}?fields={field1,field2,field3,...}

Evaluates a fulltext search on selected fields only.

Example Description
/query/a5-2?$search=monolog*& fields=Keywords &pretty Searches for "monolog*", but only in field "Keywords".
/query/a5-2?$search=communication& fields=Title,Description &pretty Searches for "communication", but only in fields "Title" and "Description".

Hit Highlighting [highlight]

GET {scheme}://{server}/query/{repository}?highlight

If set, returns field matches marked with hit highlighting.

Example Description
/query/a5-1?pretty&$search=communication&highlight Highlighted hits are shwon in field "@a5.highlight".

Facets Aggregation [facets]

GET {scheme}://{server}/query/{repository}?facets={field1[:integer],field2[:integer],...}

Includes facets aggregations for selected fields of variable size. The facets aggregation is contained in field "@a5.facets" at the bottom of the JSON result.

Example Description
/query/a5-2?pretty&facets=ObjectLanguage Matches all documentes of repository "a5-2" and includes a faceted aggregation for field "ObjectLanguage". The default size of the aggregation is 10.
/query/a5-2?pretty&facets=ObjectLanguage:5 Matches all documentes of repository "a5-2" and includes a faceted aggregation for field "ObjectLanguage". The size of the aggregation is set to 5.
/query/a5-2?pretty&facets=ObjectLanguage:10,Keywords:15 Matches all documentes of repository "a5-2" and includes facets aggregations for field "ObjectLanguage" and "Keywords". The sizes of the aggregations is set to 10 and 15.

Drilling Down with Facets [drill]

GET {scheme}://{server}/query/{repository}?drill={field1 (eq|ne|gt|ge|lt|le) "term1" (and|or|not) field2 ...}

Drills down the search result according to selected facets. The syntax is the same as for the "$filter" option.

Example Description
/query/a5-2?pretty&$search=story&facets=ObjectLanguage,Keywords&drill=ObjectLanguage eq "Bali" or ObjectLanguage eq "Vera%27a" Includes facets aggregations for fields "ObjectLanguage" and "Keywords" and drills down the search result to "ObjectLanguage eq "Bali" or ObjectLanguage eq "Vera'a"".

Query String Autocompletion [autocomplete]

GET {scheme}://{server}/query/{repository}?autocomplete

If set, includes a autocompletion aggregation for the current query string.

Example Description
/query/a5-2?pretty&$search=story&autocomplete Includes a query string autocompletion aggregation in field "@a5.autocomplete" at the bottom of the JSON result.

Pretty Printing Results [pretty]

Example Description
/query/a5-1 Prints any JSON response in compact form in format "application/json" for production use.
/query/a5-1?pretty Prints any JSON response in human readable form in format "text/plain" for debbuging only.