Search and Filtering

When using the Uniform API, you can perform precise searches and filtering within specific fields of an entry or composition. This guide provides detailed instructions to help you construct queries to achieve this functionality.

Filtering Syntax#

The Uniform API supports advanced filtering using a specific query string format:

filters.entryProperty[operator]=value

entryProperty: The name of the field within the entry or composition you wish to filter by. For example:
- propertyName for system properties. Reference: System Props
- fields.fieldName for fields added to a content type.
- parameters.parameterName for fields in compositions.
operator: The comparison operator (e.g., eq, match, gt, etc.).
value: The value you are searching for. This is treated literally and should not include quotation marks.

Example Query

Suppose you want to search for entries with the following conditions:

Project ID: xxx
Content Type: brand
Field: brandName
Value: Contains the text "Adidas"

You can construct the query as:

https://uniform.global/api/v1/entries?projectId=xxx&filters.type%5Beq%5D=brand&filters.fields.brandName%5Bmatch%5D=adidas

Note: The [ and ] characters in query strings are URL-encoded, so they can be used directly in the browser.

Reference Fields#

For reference fields, the following properties are indexed and can be filtered:

name
slug
uiStatus
type

Example Syntax:

filters.fields.refFieldId.slug[eq]=my-little-pony

Supported Operators#

For Numeric Fields:

Operator	Description
`eq`	Equal to
`neq`	Not equal to
`gt`	Greater than
`gte`	Greater than or equal to
`lt`	Less than
`lte`	Less than or equal to

For Custom Fields:

Operator	Description
`match`	Contains a specific string
`starts`	Starts with a specific string
`eq`	Equals a specific value
`neq`	Does not equal a specific value
`in`	Matches any value in a list
`nin`	Does not match any value in a list
`gt`	Greater than
`gte`	Greater than or equal
`lt`	Less than
`lte`	Less than or equal
`def`	Defined (has a value)

For Entity Identifiers (ID, Type, UI Status):

Operator	Description
`eq`	Equals a specific string
`neq`	Not equal to a specific string
`in`	Matches any value in a list
`nin`	Does not match any value in a list

For Date Fields (Created, Modified):

Operator	Description
`eq`	Equals a specific date
`neq`	Not equal to a specific date
`in`	Matches any date in a list
`nin`	Does not match any date in a list
`gt`	After a specific date
`gte`	On or after a specific date
`lt`	Before a specific date
`lte`	On or before a specific date

For Optional String Fields (Locale, Pattern ID, Workflow ID/Stage):

Operator	Description
`eq`	Equals a specific string
`neq`	Not equal to a specific string
`in`	Matches any value in a list
`nin`	Does not match any value in a list
`def`	Field is defined (has a value)

For Always Present String Fields (Name, Slug, Creator, Author):

Operator	Description
`match`	Contains a specific string
`starts`	Starts with a specific string
`eq`	Equals a specific value
`neq`	Does not equal a specific value
`in`	Matches any value in a list
`nin`	Does not match any value in a list

Using the SDK#

For Entries

When using the Uniform SDK to fetch entries, the filtering syntax is as follows:

contentClient.getEntries({ filters: { 'type[eq]': 'brand', 'fields.brandName[match]': 'adidas', }, });

For Compositions

When fetching compositions, use the following syntax:

canvasClient.getCompositions({ filters: { 'type[eq]': 'brand', 'parameters.brandName[match]': 'adidas', }, });

Example Use Cases#

Scenario: Find an Entry with Specific Numeric Field Value

You want to find an entry of content type hyperlink with a numeric field objectId equal to 8.

API Query:

https://uniform.global/api/v1/entries?projectId=xxx&filters.type%5Beq%5D=hyperlink&filters.fields.objectId%5Beq%5D=8

SDK Query:

contentClient.getEntries({ filters: { 'type[eq]': 'hyperlink', 'fields.objectId[eq]': 8, }, });

Scenario: Find a Composition with Specific Parameter Value

You want to find a composition with a parameter brandName containing the text "Nike".

API Query:

https://uniform.global/api/v1/compositions?projectId=xxx&filters.parameters.brandName%5Bmatch%5D=nike

SDK Query:

canvasClient.getCompositions({ filters: { 'parameters.brandName[match]': 'nike', }, });

Enhanced Filtering with Faceting#

In addition to the standard filtering capabilities, the Uniform API now supports faceting, a powerful feature that allows you to aggregate and categorize your search results further. This functionality is marked as deprecated in the SDK, as it is subject to change.

Faceting Syntax

You can use the ?facetBy= query string parameter to specify the field by which you want to facet your data. This parameter supports both system fields and fields from content types or parameters from components.

- System Fields: ?facetBy=fieldName Reference: System Props

- Content Type Fields: ?facetBy=fields.fieldName

- Component Parameters: ?facetBy=parameters.parameterName

Note: Only numerical values and short text values are facetable. Rich text fields and similar are not supported.

Faceting with Reference Properties

For reference fields, the following properties can be faceted:

name
slug
uiStatus
id

Example Syntax:

?facetBy=fields.(refFieldId).(property)

Note:

When faceting by a field, it is crucial to provide the content type in your query due to the requirement for a single content type filter.

API Query:

https://uniform.global/api/v1/entries?projectId=xxx&facetBy=fields.additionalSpeakers.slug&filters.type\[eq\]=eventSession'

SDK Query:

contentClient.getEntries({ filters: { 'type[eq]': 'eventSession' }, facetBy: 'fields.additionalSpeakers.slug', });

Attempting to facet by a field without specifying a single content type will result in an error similar to:

{ "errorMessage": "Cannot facet by field without a single type", "name": "BadRequestError" }

Notes#

Ensure you use the correct data type for the value being filtered.
For numeric comparisons, ensure the field is of numeric type in your content model.
Combine multiple filters in a single query to narrow down results.
Search in nested objects is not supported: Parameter of a component in a composition, field of a block in an entry

Need More Help?#

If you have additional questions or require assistance with specific scenarios, feel free to reach out to our support team.