Search

POST /api/v1/search?token=<token>

Search user objects and base objects.

Query String

Input

The input is provided as a JSON object with the following attributes:

The parameters offset and limit can be used to scroll through large amount of results. Use the response attribute count to control the total number of hits. limit can also be set to 0 if only aggregations are needed.

best_mask_filter is only meaningful for search type “object”. It prevents retrieving duplicate objects rendered in different masks.

• the corresponding base config variable (system.log.search, system.log.detail) is set to true

The option exclude_fields exclude parts of the output.

The option include_fields include object’s fields to the output and it is processed after exclude_fields. Excluded fields could be returned if they are present in include_fields.

The format as described below is the basis for the field list. It predefines the list of fields returned, which can be further refined with exclude_fields and include_fields. There is no guarantee that all fields in exclude_fields are actually missing. If a fields is required for internal use (e.g. _id) it may be returned anyway.

Search type

The following search types are supported:

• object (default): search user-defined objects (see object) with read and mask
• pool: search pools with bag_read
• pool_management: search pools with bag_write
• collection: search collections (see collection)
• message: search messages (see message)
• user: search users (see user) with read and type “easydb”, “system” or “email”
• group: search groups (see group) with bag_read
• acl: search users and groups simultaneously

Search elements

The search elements act like filters over the search. The parameter “bool” determines if the search element has to be true (“must”) or false (“must_not”) for an object to be found. If there are several search elements marked as “should” it means that at least one of them must apply for an object to be found.

If no search elements are given, all elements of the given type(s) are returned.

The common parameters for a search element are:

Example:

{
    "search": [
        {
            "type": "in", // search elements from pools 1, 3 and 4 ...
            "bool": "must",
            "fields": [
                "images._pool.pool._id"
            ],
            "in": [
                1,
                3,
                4
            ]
        },
        {
            "type": "match", // ... that match "house" in any field ...
            "bool": "must",
            "mode": "token",
            "string": "house",
        },
        {
            "type": "match", // ... but not preceded by "white"
            "bool": "must_not",
            "mode": "token",
            "string": "white house",
            "phrase": true
        }
    ]
}

Example using boost:

Objects matching “house” will have a higher _score than those matching “appartment”.

{
    "search": [
        {
            "type": "in", // search elements from pools 1, 3 and 4 ...
            "bool": "must",
            "fields": [
                "images._pool.pool._id"
            ],
            "in": [
                1,
                3,
                4
            ]
        },
        {
            "type": "match", // ... that should match "house" in any field ...
            "bool": "should",
            "mode": "token",
            "string": "house",
            "boost": 3
        },
        {
            "type": "match", // ... and should match "appartment" in any field ...
            "bool": "should",
            "mode": "token",
            "string": "appartment"
        }
    ]
}

search element “match”

This search element allows to match a given text. It can be used with all search types. Match ignores case and diacritical marks, and detects some writing variants. For instance, “fusse” will match “Füße”.

This search element can only be applied to Text, String and L10n fields. The languages restrict the languages L10n fields are searched for. If no fields parameter is set, every searchable field of the required types will be considered.

The search mode “token” matches whole words, whereas “fulltext” matches parts of words. Notice that Text and L10n fields only match words beginning with a particular token. String fields will also match inside the text. The “wildcard” mode allows to specify * and ? wildcards to match the text in more complex forms. This kind of search is slower though, especially when using * at the beginning.

For String fields, the string is matched against the whole field.

For Text and L10n fields, the string is divided into words and then matched against the words contained in the field. If phrase is set to true, the words must be found in the same order as given, and may not include other words in between. phrase is ignored when using wildcards.

Examples:

{
    "type": "match", // find tokens "house" and "sea" in book titles and image names, only in en-US
    "bool": "must",
    "mode": "token",
    "string": "house sea",
    "fields": [
        "book.title",
        "image.name"
    ],
    "language": [
        "en-US"
    ]
}

search element “in”

Search for specific values in one or more fields.

One of fields, objecttype or eas_field has to be provided.

If a single field is given, the type of in will depend on the field type. Allowed types are:

Notice that null is always allowed, in order to be able to search entries with no value.

If more than one field are given, all of them must be of the same class. A dis_max query is used.

If objecttype is used, all fields linking to an element of that objecttype are considered. The special name _pool is used to search in all pool fields. The value type of in will be a number and it represents the ID of that objecttype / pool.

If objecttype is used, the attribute include_path can be used to search also by the objects contained in the path. This has no effect on non hierarchical objecttypes, but it can be used for them, too.

If eas_field is used, all assets linked by the object considered. The eas_field is the asset field searched (for example: "class"), and in contains the values (for example "image" and "video").

(*) All text and string values are truncated at 256 characters in elasticsearch. Every text and string input value that is longer than 256 characters will cause an UserError (error.user.search_query_too_long).

(**) L10n fields will be expanded to the given languages.

Examples:

{
    "type": "in", // number
    "fields": [
        "published_year",
        "written_year"
    ],
    "in": [
        1900,
        1920,
        null
    ] // null is always possible
}

{
    "type": "in", // string
    "fields": [
        "author",
        "title"
    ], // Text + L10n
    "in": [
        "Goethe"
    ]
}

{
    "type": "in", // elements linking to artists 1, 2 or 3
    "objecttype": "artist",
    "in": [
        1,
        2,
        3
    ]
}

{
    "type": "in", // elements in pools 1, 2 or 3
    "objecttype": "_pool",
    "in": [
        1,
        2,
        3
    ]
}

search element “range”

This search element allows to match numeric (Number, Id), date/time (Date, Timestamp) or string (String) fields using a range.

Dates are given in ISO 8601 format. Both from or to or one of them must be given.

Example:

{
    "type": "range", // find books that were published between Jan 15th and Feb 15th 2000
    "bool": "must",
    "field": "book.published",
    "from": "2000-01-15T00:00:00Z",
    "to": "2000-02-15T00:00:00Z"
}

search element “changelog_range”

This is a special search element that allows to search for a objects that were changed by a specific user in a given period of time.

Dates are given in ISO 8601 format, in UTC, and may be provided as a date prefix. Both from or to or one of them must be given.

search element “nested”

This search element allows to retreive documents that match against a query for their nested documents. It is like a complex search that is performed at a certain path inside the main object type and returns objects from the main object type, but is run against the nested object type.

Example:

{
    "type": "nested", // find paintings that use the techniques "airbrush" and/or "oil"
    "path": "painting._nested:painting__technique",
    "search": [
        {
            "type": "in",
            "bool": "must",
            "field": [
                "painting._nested:painting__technique.tech.technique.name"
            ],
            "in": [
                "airbrush",
                "oil"
            ]
        }
    ]
}

search element “complex”

This search element allows to specify more complex search expressions by nesting them in the global search. The normal search already allows some combinations, like “A or B or C”:

Example:

{
    "search": [
        {
            "bool": "should",
            ...
        }, // A
        {
            "bool": "should",
            ...
        }, // B
        {
            "bool": "should",
            ...
        } // C
    ]
}

But other combinations are not covered, like “(A and B) or C”. For that, you can use the “complex” search type:

Example:

{
    "search": [
        {
            "bool": "should",
            "type": "complex",
            "search": [
                {
                    "bool": "must", 
                    ...
                }, // A
                {
                    "bool": "must", 
                    ...
                } // B
            ]
        },
        {
            "bool": "should", 
            ...
        } // C
    ]
}

Field names

Generic fields used for searching and sorting

Top level object

Changelog

EAS column

Main tables

Hierarchical linked tables

Linked tables at top level

Object fields

Sorting

It is possible to define sorting fields by arranging sorting definitions in an array. Each sorting definition will be taken into account in the order they are given. A sorting definition is composed of:

All fields present in the index are sortable. There are some special cases to consider:

Sorting by string fields

Strings can be sorted alphabetical or alphanumeric by setting the flag numeric.

See String sorting

Sorting by l10n fields

L10n fields will be expanded to the given lang. The default value for language is:

• the “language” defined at top level, for regular fields
• the frontend language of the user, for the special field _pool (see below)

See Multilanguage sorting

Example:

{
    "sort": [ // sort by author (alphabetically) and year (last ones first)
        {
            "field": "book.author"
        },
        {
            "field": "book.year",
            "order": "DESC"
        }
    ]
}

Hierarchical pool sorting

Additionally, the field _pool allows to sort by pool hierarchy. At each level, the pools are ordered by name (l10n). Then, the children pools are ordered recursively, depth-first. The objects are ordered depending on the pool they are in. Objects without pool come at the beginning.

See the following example:

• Pool “Animals” (1)
  • Pool “Cats” (2)
  • Pool “Zebras” (3)
• Pool “Trees” (4)
  • Pool “Oaks” (5)

The numbers in parentheses are the numbers used for sorting. Notice that “Oaks” come after “Zebras” because the parent pools are “Trees” (second place) and “Animals” (first place), respectively.

Example:

{
    "sort": [ // sort by pool and book title
        {
            "field": "_pool"
        },
        {
            "field": "book.title"
        }
    ]
}

Fields that are marked as Nested can use a nested_filter when sorting that defines which values are picked for sorting the objects. Only fields of numeric, boolean or string/text types can be used.

Sorting by dates and dateranges

Sorting by date fields can be done by specifying the date field with or without the suffix .value. If .value is not appended to the fieldname, the server will assume this as the internal subfield for date values.

For sorting by dateranges, you have to specify if you want to sort by the start date (.from) or by the end date (.to).

Example:

{
    "sort": [ 
        // sort by date field
        {
            "field": "object.date", // or "object.date.value"
            "order": "ASC"
        },
        // sort by start date of daterange field
        {
            "field": "object.daterange.from",
            "order": "ASC"
        },
        // sort by end date of daterange field
        {
            "field": "object.daterange.to",
            "order": "ASC"
        }
    ]
}

Nested sorting

The specification of the nested_filter is a map from fields (using only the field name, not the whole field path) to an array of terms.

Sorting by linked objects

When sorting by linked objects, the whole hierarchy is considered by default. By using with_path: false, you can override this behaviour.

Sorting by score

Also it is possible to use the field _score which allows to sort by the relevance of the object in the search. The more should clauses that match, the more relevant the object.

Output: sort

When sorting fields are defined each object will includes an attribute _sort with an array of values used to sort, one value per sorting field. Sort values are in a binary format and can be used for per-byte based sorting.

Aggregations

It is possible to aggregate data based on the search query using so-called “aggregations”. Field’s data is aggregated only if one (or both) of the options “Advanced Search” or “Filter” is enabled in mask’s search settings for the field.

The requests accepts several aggregations, which are applied independently to the result set. They are identified by an arbitrary name which is used as key for the “aggregations” object.

Example:

{
    "language": [
        "de-DE"
    ],
    "aggregations": {                // Calculate the following aggregations based on the search results
        "countries": {               // - number of authors by country (in German due to "culture")
            "type": "term",
            "fields": [
                "author.country"
            ],
            "sort": "term"
        },
        "pages": {
            "type": "term_stats",    // - statistics on pages by book type
            "field": "book.type",
            "value_field": "book.number_of_pages"
        },
        "pools": {
            "type": "linked_object", // - elements by pool hierarchy
            "field": "_pool"
        }
    }
}

The aggregation definition has the following common properties:

Other properties depend on the aggregation type:

Aggregation type “term”

This aggregation type returns the most frequent terms along with the document count for each one. If any of the given fields is an L10n field, it will be expanded by languages.

Example:

The following example gets the top 5 genres along with the book count for each one of them:

{
    "aggregations": {
        "genre": {
            "type": "term",
            "field": "book.genre",
            "limit": 5
        }
    }
}

Notice that any indexed field can be given, including fields that are not marked for aggregations in the mask definition.

This aggregation type should be used when aggregating over tags. Since the tag ID is an indexed field, the type "term" can be used:

{
    "aggregations": {
        "_tags": {
            "type": "term",
            "field": "_tags._id"
        }
    }
}

Aggregation type “term_stats”

This aggregation operates over a field in the same way that the aggregation type “term” does, but instead of document counts, it gives statistical information about the values taken from another field (value_field).

Example:

The following example returns statistical information about the readers’ age by book genre:

{
    "aggregations": {
        "age_by_genre": {
            "type": "term_stats",
            "field": "book.genre",
            "value_field": "book.reader.age"
        }
    }
}

Notice that field can be any indexed field, including fields that are not marked for aggregations in the mask definition.

Aggregation type “linked_object”

This aggregation type can be used in two different ways. The first one is by providing a field. The field may be any linking field (i.e. “person.birth_place”). For objecttypes with pool link, _pool is also available.

The second way is by providing a linked object type (objecttype). The aggregation will take into account all objects of that type that a document links.

Notice that field and objecttype cannot be combined.

An additional parameter filter_parent can be set for hierachical objects (pools are always hierarchical) to filter by parent ID. It can be set to null to obtain only top level elements. The result aggregations contain the hierarchy path.

Example:

{
    "objecttypes": [
        "person"
    ],
    "aggregations": {
        "departments": {
            "type": "linked_object",
            "field": "person.department"
        },
        "contacts": {                // if "person" has different "person" links (i.e. person.friends, person.relatives),
            "type": "linked_object", // we want to aggregate by contacts, but unique for each person
            "objecttype": "person"
        },
        "pools": {                   // aggregate by pool, filtered by parent (also available for hierarchical linked objects)
            "type": "linked_object",
            "field": "_pool",
            "filter_parent": 5
        }
    }
}

Notice that in this case the mask definition matters: only if a linked object is marked for aggregations in the mask definition, it will be taken into account for aggregating.

Aggregation type “asset”

This aggregation type uses all preferred assets of a document and lets perform a term aggregation over them.

Allowed values for field are:

• "class_extension"

  • aggregate over combinations of class and extension of assets
  • result example: ["image.jpg", "image.png"]

• "class_version_status"

  • aggregate over combinations of class, version and status of assets
  • result example: ["image.original.done", "image.preview.done"]

• "class_version_extension"

  • aggregate over combinations of class, version and extension of assets
  • result example: ["image.original.jpg", "image.preview.jpg"]

• "class_version_filesize"

  • aggregate over combinations of class, version and filesize of assets
  • result example: ["image.original.4096", "image.preview.1024"]

Example:

{
    "aggregation": {
        "by_class_extension": {
            "type": "asset",
            "field": "class_extension"
        }
    }
}

Notice that in this case the mask definition matters: only if an asset field is marked for aggregations in the mask definition, it will be taken into account for aggregating.

Aggregation type “date_range”

This aggregation type uses date or date_range fields to aggregate over date ranges.

Per default, if a daterange field is used for aggregating, the internal sub field _from is used (the start date of the date range). The sub fields _to (end date of the daterange) and _from can be specified in the request by adding the suffix .to or .from respectivly to the field.

The aggregation results will contain the number of objects (doc_count). This information can be used to generate searches for these objects or date histograms.

ranges

In the array ranges multiple (at least one!) ranges can be defined. For each range all field values that can be parsed as valid datetime strings, and are inside the range limits, are grouped.

For date fields, the date value (_value) will be used for the aggregation. For date_range fields, the start value (_from) will be used for the aggregation.

format

Valid timestamp formats are:

• date

  • requires date values in the format YYYY-MM-DD
  • Example: 2019-01-01

• date_time_simple

  • requires datetime values in the format YYYY-MM-DDTHH:mm:SS
  • Example: 2019-01-01T23:59:00

• date_time (ISO 8601 format)

  • requires datetime values in the format YYYY-MM-DDTHH:mm:SS.000Z
  • Example: 2019-01-01T23:59:00.000Z

If any other value is used as the format, the server will throw an API error.

The format of the timestamps used in ranges must match the specified format. Otherwise, Elasticsearch will throw an error.

Request:

Aggregate the date field publish_date of book, group by 19th and 20th century.

{
    "aggregations": {
        "type": "date_range",
        "field": "book.publish_date",
        "format": "date",
        "ranges": [
            {
                // get all books published in the 20th century
                // (where the date in the field book.publish_date lies in between this range)
                "to": "1999-12-31",
                "from": "1900-01-01"
            },
            {
                // get all books published in the 19th century
                // (where the date in the field book.publish_date lies in between this range)
                "to": "1899-12-31",
                "from": "1800-01-01"
            }
        ]
    }
}

Response:

The value of field from the request will be used as the key for the aggregation in the response.

For each element in ranges, there will be a corresponding object in the array buckets.

The value doc_count returns the number of objects where there is a date or date range field, where the value is in the range.

The values from and to are the same that have been given in the request.

They can be used to perform a range search to get the actual objects. The search should return the same number of objects as is indicated by doc_count.

{
    "aggregations": {
        "book.publish_date": {
            // this array contains the aggregation results
            // each object in 'buckets' contains the number of objects where
            // the date in the field book.publish_date lies in between this range
            "buckets": [
                {
                    // there are 100 books that have been published in the 20th century
                    "doc_count": 100,
                    "to": "1999-12-31",
                    "from": "1900-01-01",
                    "key": "1900-01-01-1999-12-31"
                },
                {
                    // there are 70 books that have been published in the 20th century
                    "doc_count": 70,
                    "to": "1899-12-31",
                    "from": "1800-01-01",
                    "key": "1800-01-01-1899-12-31"
                }
            ]
        }
    }
}

Highlighting

It is possible to generate highlighted versions on the fields that match the search request. The highlight definition can be just an empty object.

The tags can be anything, not only HTML tags.

Example:

{
    "highlight": { // Enclose highlighted text in * ... *
        "pre_tag": "*",
        "post_tag": "*",
        "escape_html": false
    }
}

The results will now contain extra fields called <field>:highlight with the highlighted text (see “Output”).

Fields

It is possible to select specific fields from the object to be returned. This is particularly interesting when using a format different than full, although it can also be used in combination with it.

The fields specification is given as an array of objects with the following attributes:

As field name, the following is accepted:

• a fully qualified regular field
• the path to a linked object
• the path to a pool link
• the special field _pool, which expands to all available pool links for the given objecttypes

The key can be used to group fields.

mode can only be used with numerical fields and it cannot be different for the same key. If mode is not provided, all values are returned.

Example:

{
    "objecttypes": [
        "Book",
        "Film",
        "Painting",
        "Person"
    ],
    "fields": [
        {
            "field": "Book.isbn"          // the key is "Book.isbn"
        },
        {
            "field": "Book.title",        // under the key "title", you can find the next fields
            "key": "title"
        },
        {
            "field": "Film.title",
            "key": "title"
        },
        {
            "field": "Painting.title",
            "key": "title"
        },
        {
            "field": "Book._pool"         // direct reference to a pool
        },
        {
            "field": "_pool"              // all pools (Book, Film, Painting, Person)
        },
        {
            "field": "Person.birthplace", // a hierarchical object
            "key": "birthplace"
        }
    ],
    ...
}

Output

The output is given as a JSON object. The following attributes are provided as a copy of the input:

The rest is the real output of the search:

For each object, the _source is returned unless format is different from full, see below. Additionally, the object will be annotated with highlights, if the request specified them. See “Output: highlights” below.

If best_mask_filter is set to false, each object contains a _best_mask field (true or false, on the same level as _mask) which indicates whether the object is rendered using the “best mask”. The _best_mask field is not present in “short” objects.

If generate_rights is true, the objects will be rendered with the parameter _generated_rights (see object).

For user objects, several l10n fields are given in just one language, following this rule:

• if the user has specified a preferred frontend language and the field has a non-empty value for that language, this is the chosen language
• if not, do the same for the first database language among the preferred user database languages
• if not, do the same for the first database language among the configured database languages
• if not, take the first language with a non-empty value
• if not, return the first language

This affects the _standard fields, as well as the pool names.

Output: format

The format option only applies to user objects. See the object for a description of the formats.

Notice that for the search, the short and standard format also imply that linked and nested objects are not rendered at all. The _standard field is provided in the selected language.

• The full format returns all object’s attributes, including _changelog. The full parameter exists since release 5.34.

• The long format returns all object’s attributes, except for _changelog. Note that this was included until release 5.33.

• The short format returns minimal attributes for refering to an object.

Example for the short format:

{
    "_format": "short",
    "_mask": "default_for_location",
    "_objecttype": "location",
    "_global_object_id": "34@easy5-university",
    "_has_children": true,
    "_score": 1.8092787,
    "_system_object_id": 2,
    "_tags": [],
    "_uuid": "aeadfca2-5287-4621-981c-5c4ea556cdfd",
    "_last_modified": "2017-09-15T08:28:52Z",
    "location": {
        "_id": 34,
        "_id_parent": 27,
        "_version": 3
    }
}

• The standard format returns attributes needed to have a preview of the objects.

Example for the standard format:

{
    "_format": "standard",
    "_mask": "default_for_location",
    "_objecttype": "location",
    "_global_object_id": "34@easy5-university",
    "_has_children": true,
    "_score": 1.8092787,
    "_system_object_id": 2,
    "_tags": [],
    "_uuid": "2954345f-1a04-46c4-ba2c-b5a39ef5e76c",
    "_last_modified": "2017-09-05T06:56:46Z",
    "_standard": {
        "eas": {
            "filesize": 82558,
            "date_inserted": "2017-09-05T08:56:46+02:00",
            "original_filename": "pf_entree12.jpg",
            "versions": {
                "small": {
                    "url": "http://easdbdev.4.0.mad.pf-berlin.de/eas/partitions-inline/2/1000/1000763000/1000763426/58c9dfeadc0e4385691d616338db92d355835206/image/jpeg",
                    "height": 250,
                    "width": 375,
                    "extension": "jpg",
                    "filesize": 12122
                    ...
                }
            },
            "extension": "jpg",
            "original_filename_basename": "pf_entree12.jpg",
            "technical_metadata": {
                "format": "landscape",
                "width": 1920,
                "height": 1280,
                "dpi": 71,
                ...
            },
            "class_extension": "image.jpg",
            "date_uploaded": "2017-09-05T08:55:33+02:00",
            "compiled": "jpg image, 1920 x 1280 @ 24 bit, 80.6 kB",
            "class": "image",
            "upload_user": {
                "user": {
                    "login": "root",
                    "_id": 1
                }
            }
        },
        "1": {
            "text": {
                "en-US": "Colorado"
            },
            "html": {
                "en-US": "<span class \"ez-output-1\"><span class=\"ez-design-normal ez-format-comma\">Colorado</span></span>"
            }
        }
    },
    "location": {
        "_version": 1,
        "_id": 34,
        "_id_parent": null,
        "_pool": {
            "pool": {
                "_version": 15,
                "_id": 2,
                "_id_parent": 1,
                "name": {
                    "en-US": "Default pool"
                }
            }
        }
    }
}

Linked objects are always provided in the “standard” format.

Output: fields

The fields are given for each object under _fields. For each provided key, an array of values is given. The values are gathered from all fields associated with the key. For pool or hierarchical linked objects, the values represent the hierarchy.

Notice that the value is always an array: if there is only one value, or if a mode was provided to aggregate values to a single one, search will still return an array (of one element).

Example:

Objects returned by the example query in Fields:

[
    {
        "_objecttype": "Book",
        "_fields": {
            "Book.isbn": [
                "0-13-110163-3"
            ],
            "title": [
                "The C Programming Language"
            ],
            "Book._pool": [
                "computer science",
                "programming"
            ],
            "_pool": [ ... ], // the same as "Book._pool"
            "birthplace": []
        },
        ...
    },
    {
        "_objecttype": "Person",
        "_fields": {
            "Book.isbn": [],
            "title": [],
            "Book._pool": [],
            "_pool": [
                "customers"
            ],
            "birthplace": [
                "Germany",
                "Berlin",
                "Berlin"
            ]
        },
        ...
    }
]

Output: aggregations

The aggregation results are provided with the same structure as the requests: the aggregation name is the key, and the aggregation result the value.

has_more is set to true in case the number of results (terms or linked objects) is greater than the limit.

{
   "aggregations" : {
      "_eas" : {
         "has_more" : false,
         "limit" : 10,
         "offset" : 0,
         "terms" : [
            {
               "count" : 32,
               "term" : "image"
            },
…
            {
               "count" : 1,
               "term" : "vector3d"
            }
         ]
      },
      "_pool" : {
         "count" : 1055,
         "has_more" : true,
         "limit" : 10,
         "linked_objects" : [
            {
               "_id" : 2,
               "_path" : [
                  {
                     "_id" : 1,
                     "_id_parent" : null,
                     "text" : "Alle Pools"
                  },
                  {
                     "_id" : 2,
                     "_id_parent" : 1,
                     "text" : "Standard-Pool"
                  }
               ],
               "count" : 1000
            },
…
            {
               "_id" : 13,
               "_path" : [
                  {
                     "_id" : 1,
                     "_id_parent" : null,
                     "text" : "Alle Pools"
                  },
                  {
                     "_id" : 13,
                     "_id_parent" : 1,
                     "text" : "Testpool 8"
                  }
               ],
               "count" : 1
            }
         ],
         "offset" : 0
      },
…

Output: highlights

The highlights results are given as extra fields that appear inside the object responses, as siblings of the original fields. The highlighted field name is the field name plus ":highlight".

Note: The highlighted text will be HTML encoded as to avoid confusion with the highlight tags. This will only happen in "*:highlight" fields

Example:

{
    "objects": [
        {
            "book": {
                "title": {
                    "de-DE": "Doku schreiben ist lustig!",
                    "en-US": "Writing documentation is fun!",
                    "en-US:highlight": "Writing <em>docu</em>mentation is fun!"
                },
                "author": "Harry Harlaw",
                "author:highlight": "<em>Har</em>ry <em>Har</em>law",
                ...
            }
        }
    ]
}

HTTP status codes

Search by object ID

POST /api/v1/search?token=<token>&system_object_ids=<ids>&format=<format>&best_mask_filter=<best_mask_filter>
POST /api/v1/search?token=<token>&global_object_ids=<ids>&format=<format>&best_mask_filter=<best_mask_filter>

Search user objects by ID

Query String

Input, Output, HTTP status code

This request behaves as if a regular search with the following input was performed:

{
    "type": "object",  // search all user objects
    "limit": X,        // X is <ids>.length                             if best_mask_filter is true
                       //      <ids>.length * max(masks per objecttype) if best_mask_filter is false
    "format": "<format>",
    "best_mask_filter": <best_mask_filter>,
    "search": [
        {
            "type": "in",
            "fields": "{_system_object_id|_global_object_id}",
            "in": [ <ids> ]
        }
    ]
}