Search APIs - Tizra/Tizra-Customer-Tracker GitHub Wiki

Search term specifications and functions

As with all api operations that support both POST and GET top-level members of the JSON record and query-string parameters are equivalent. It is undefined what will happen if the same parameter appears in both places.

Individual items in search results may happen to be null. This can happen due to update anomalies and/or transient conditions; code that uses the search APIs needs to be aware of this and not crash.

Search term specifications

The search api is based on the syntax used in collection definitions. A collection is defined by 3 lists of search terms: a list of required values, a list of optional values, and a list of excluded values. Each search term has the same format, described here.

The full format is a colon-separated list of fields:

metatypeName:propertyName:value

Leading components of these fields can be eliminated. The metaTypeName will default to Book and the propertyName will default to AdminTags.

Note that the metaTypeNames used are internal names. This means that Excerpts have the type PageRange, and Collections have the type SubjectCollection . If you want to search full text, you need to search Page objects, which are not normally visible in lists, etc. They have the type PdfPage.

There is one special case: a two part query with a propertyName of MetaType will create a search term that matches only objects of that type.

To search full text, rather than metadata you must use the pseudo-property pageFullText. This is normally present only on the hidden Page objects, but advanced site settings can be used so that Excerpts (or even books) will have a full text search field containing the entire text. This is generally useful for "article-style" searches of book chapters where page-level results are not desired.

It is not currently possible to set the language of a search term, though this will change in the future.

The /api/search and /api/search-count operations

These two operations return a paginated search result list, or a simple count of the number of results from the search.

A simple search on a list of required terms can be made by posting a JSON Array of search terms:

[
	"Keywords:introduction",
	"Region:South America"
]

A full query is made by means of a JSON record:

{
   "meta-type": "Book",
   "any": ["Region:South America", "Region:North America"],
   "all": ["Keywords:introduction"],
   "excluding": ["Keywords:advanced"],
   "filter-collection-id": "tizra-id"
}
  • meta-type is a mandatory specification of an overall limit for result types. The type AdminTagged can be used, as elsewhere, to specify no limitations other than those that might be imposed by the query terms themselves.
  • any, all, and excluding are optional arrays of query terms.
  • filter-collection-id if specified further limits the results to items contained in a given Tizra collection. The collection is usually expressed as a tizra-id, but can be a numerical value as well.

The /api/prop-values operation

Returns a JSON array of values for a given field, restricted by a search query or metatype. These can be simple strings, or JSON records including values, as well as the number of occurences of those values.

Parameters to the GET and POST operations are compatible:

  • meta-type The type of object being searched
  • prop-names Repeatable parameter specifying property values of interest
  • full-info If true, specifies that the results should be records of information about each term, including the number of occurrences.
  • prefix Prefix that must be present for a value to be enumerated. This field should not repeat. Results are currently undefined if multiple properties are specified for prop-names.
  • sort-values Should the values be sorted alphabetically
  • filter-licenses true if views should be limited to content the user and current session can access.
  • filter-collection-id tizra-id of a collection to filter by

For example a URL like http://autotest.autotest.com:8080/api/prop-values?meta-type=Book&prop-names=Keywords&full-info=true might return something like the following:

[
    {
        "count": 18, 
        "value": "blarg"
    }, 
    {
        "count": 5, 
        "value": "Engineering"
    }, 
    {
        "count": 3, 
        "value": "American Studies"
    }, 
    {
        "count": 3, 
        "value": "digital rare book"
    }, 
    {
        "count": 2, 
        "value": "Appalachian Trail"
    }, 
    {
        "count": 2, 
        "value": "Application Notes"
    }, 
    {
        "count": 2, 
        "value": "Bear Mt."
    }, 
    {
        "count": 2, 
        "value": "Beartown State Forest"
    }, 
    {
        "count": 2, 
        "value": "Becket"
    }, 
    {
        "count": 1, 
        "value": "databook"
    }, 
    {
        "count": 1, 
        "value": "eighteenth century"
    }, 
    {
        "count": 1, 
        "value": "electronic"
    }, 
    {
        "count": 1, 
        "value": "ic"
    }, 
    {
        "count": 1, 
        "value": "iso"
    }, 
    {
        "count": 1, 
        "value": "l4940xx10"
    }, 
    {
        "count": 1, 
        "value": "l4940xx12"
    }, 
    {
        "count": 1, 
        "value": "l4940xx5"
    }
]

The POST operation adds the parameters "all", "any", and "excluded", which specify a limiting search, just as in the /api/search operation.

A POST to the url /api/prop-values might look like this: { "meta-type":"Book", "all": ["AdminTags:zarg"], "prop-names": ["Title", "Authors"] }

When multiple prop-names are supplied the result, rather than a JSON array of results, will be a JSON record, holding several such result arrays:

{
    "Authors": [
        "Gavin King and others", 
        "Tingle", 
        "amazon", 
        "tangle", 
        "this: death", 
        "time;too"
    ], 
    "Title": [
        "AC", 
        "EXP.pdf", 
        "Hibernate Annotations Reference Guide 3.5.6-Final", 
        "Observations Maya Hieroglyphic writing", 
        "amazon ec2"
    ]
}