Skip to main content
GET
Search Data Objects
The Search Data Objects endpoint allows you to search through your master data across business areas, schemas, and datasets. You can perform full-text searches and filter results based on your organizational structure.

Prerequisites

  • A Pretectum API key (see API Keys)
  • Permission to search data objects in your tenant

Authentication

Include your API key in the Authorization header.

Request

Query Parameters

string
required
The search query string. This supports full-text search across all indexed fields in your data objects. You can use standard search operators like AND, OR, and wildcards (*).Examples:
  • John - Search for “John” in any field
  • John AND Smith - Search for records containing both “John” and “Smith”
  • email:*@example.com - Search for email addresses ending with @example.com
string
Filter results to a specific business area by name. If not provided or set to “all”, the search will include all business areas you have access to.Use the List Business Areas endpoint to get the available business area names for your application.Example: Customer, Product, Supplier
string
Filter results to a specific schema by name. A schema defines the structure and fields of your data objects within a business area.Use the List Schemas endpoint to get the available schema names for a business area.Example: Individual Customer, Business Customer
string
Filter results to a specific dataset by name. Datasets are collections of data objects that share the same schema.Use the List Datasets endpoint to get the available dataset names for a schema.Example: US Customers, European Customers
number
default:"0"
The starting position for pagination. Use this to skip a number of results for implementing pagination.Example: 0 (start from the first result), 10 (start from the 11th result)
number
default:"10"
The maximum number of results to return. Use this in combination with from for pagination.Example: 10, 25, 50

Headers

string
required
Your Pretectum API key. Create one in the Pretectum app under Configuration → API Keys.

Example Requests

Response

A successful search returns a list of matching data objects and the total count.
array
required
An array of data objects matching your search query. Each object contains the data fields defined in its schema plus metadata fields.
number
required
The total number of data objects matching your search query. Use this with from and size parameters for pagination.

Example Response

Empty Results

When no data objects match your query, the response will contain an empty hits array:

Error Responses

Search Query Syntax

The query parameter supports two types of searches: full-text search for finding terms across all fields, and field-specific search for filtering by specific attribute values. Full-text search looks for matching terms across all indexed fields in your data objects.

Comparison Operators

You can also use comparison operators with bracket notation for field names. This syntax is useful when field names contain spaces or special characters.

Combining Comparison Operators

You can combine multiple comparison operators using and and or keywords.

Mixing Query Styles

You can combine bracket notation with standard field syntax in the same query.

Field-Specific Search (Attribute Filtering)

Filter records by specific attribute values using the field:value syntax. This allows you to target searches to particular fields in your data objects.

Numeric and Date Range Queries

Use range syntax to filter by numeric values or dates.

Nested Object Queries

For data objects with nested attributes, use dot notation to access nested fields.

Escaping Special Characters

If your search term contains special characters, escape them with a backslash (\). Special characters: + - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /

Query Examples by Use Case

Pagination

For large result sets, use pagination to retrieve results in smaller batches:
Use the total field in the response to determine the total number of pages available.

Best Practices

  1. Use specific queries: More specific queries return more relevant results and perform better.
  2. Filter by business area: When possible, filter by businessArea to narrow your search scope.
  3. Implement pagination: Always paginate large result sets to improve performance.
  4. Handle empty results: Your application should gracefully handle cases where no results are found.
  5. Reuse one key: An API key does not expire on its own, so hold it in configuration rather than fetching a credential per request.