Search and Filtering

Problem Statement

You need to find entries or compositions matching specific field values via the Uniform API or SDK. The API supports a query-string filter syntax, typed comparison operators, and faceting for aggregating results.

Solution

1. Build a filter expression

Use the format filters.entryProperty[operator]=value:

• entryProperty: propertyName for system properties, fields.fieldName for content type fields, parameters.parameterName for composition parameters.

• operator: comparison operator (eq, match, gt, ...).

• value: treated literally — no quotation marks.

Example — entries of type brand whose brandName contains "Adidas" ([ and ] are URL-encoded; you can use them directly in the browser):

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

For reference fields, the indexed properties are name, slug, uiStatus, and type:

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

2. Pick the right operator

Operators: eq/neq (equals / not), match (contains), starts (starts with), in/nin (in list / not in list), gt/gte/lt/lte (greater/less than, or-equal), def (field has a value).

3. Filter via the SDK

Entries:

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

Compositions:

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

More examples — entry of type hyperlink with numeric field objectId equal to 8:

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

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

Composition with parameter brandName containing "Nike":

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

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

4. Aggregate results with faceting

Add ?facetBy= to categorize results (marked deprecated in the SDK — subject to change). Only numerical and short text values are facetable; rich text is not.

• System fields: ?facetBy=fieldName

• Content type fields: ?facetBy=fields.fieldName

• Component parameters: ?facetBy=parameters.parameterName

• Reference field properties (name, slug, uiStatus, id): ?facetBy=fields.(refFieldId).(property)

Faceting by a field requires a single content type filter in the query:

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

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

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

Troubleshooting

Verify it works: open the example API query in a browser with your projectId — the response should contain only entries matching your filters. Combine multiple filters in one query to narrow results.

"Cannot facet by field without a single type" (BadRequestError): add a single content type filter (e.g. filters.type[eq]=...) when faceting by a field.

Filter returns nothing: check the value's data type matches the field (numeric comparisons need a numeric field in the content model). Note that nested objects are not searchable — parameters of a component inside a composition, or fields of a block inside an entry.