API Reference

Master Datav1 Guides
Querying documents in Master Data v1

There are two ways to search for Master Data v1 documents:

Query by document ID

The ID is the most efficient reference to the exact storage address, so this type of query is the fastest way of recovering data. We recommend using the GET Get document endpoint to retrieve a document by its ID.

Query a collection of documents

In this type of search, the fields marked as Is searchable? or Is filterable? and the fields set as indices in Master Data v1 data entity settings determine results. But they are not the only ones you should use. The indices are also part of this process. The best way of understanding the flow of this type of search is to look at an example.

In the example below, there is a data entity called Client, with the CL acronym, configured as follows:

Field nameTypeIs filterable?Is searchable?
NameVarchar 100NoYes
SizeVarchar 10NoNo

Is filterable?

The Is filterable? attribute indicates that we can use a filter via a specific field or fields. Following the example, we can filter through the fields Email and Age.

Using the GET Search documents endpoint of Master Data API - v1, we can make the following queries:

  • Filter by Email: /dataentities/CL/search?
  • Filter by Age: /dataentities/CL/search?Age=18

If a filter is used in the Name, field, which is not marked as a filter, the answer will be Bad Request indicating that the Name field is not configured as a filter.

Is searchable?

The attribute Is searchable? indicates that we can search this field's values via the _keyword attribute in the GET Search documents endpoint of Master Data API - v1.

The _keyword would be used, for example, to retrieve all the documents containing the value mary.

In this case, the API path would be: /dataentities/CL/search?_keyword=maria

Asterisks are indicators for a partial query. In other words, documents with the exact value mary, will not be searched for, but only those showing this group of characters somewhere.

The result of this query would return documents with values such as the following in the attributes Name and Email: Name=Mary Lee |


An index works as a shortcut to find documents. Using this resource, the query is quicker than with a normal filter or keyword search.

However, the greater the number of indexes, the more slowly documents are written. The use of the index is recommended for search results of up to 1 thousand documents.

Queries by indexes can be made through the GET Search documents endpoint. In the search flow, when Master Data interprets a query, it checks if the filter is part of an index and, if so, the search is done through the index.


Master Data reindexing is a background process that works as follows:

  1. It reads the configurations of fields marked as Is filterable? and Is searchable?.
  2. It updates the search engine with the new fields.
  3. It searches all stored documents and updates the values in the search engine.

When the fields of a document are written in the search engine, it means this document is indexed.

This process only happens when fields marked as Is filterable? or Is searchable? are changed.

Photo of the contributor
+ 1 contributors
Was this helpful?
Suggest edits (Github)
Photo of the contributor
+ 1 contributors
On this page