Skip to content

PROGX-1276: Add reference entity record attribute filtering documentation #1143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

PROGX-1276: Add reference entity record attribute filtering documentation #1143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8adf2d0
PROGX-1068: Add reference entity record attribute filtering documenta…
jessyjurkowski Nov 3, 2025
e4bfc5d
PROGX-1276: Update documentation for records filter by API for option…
jessyjurkowski Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions content/concepts/reference-entities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -322,6 +322,9 @@ Below is the JSON standard format representing a reference entity record.
::: panel-link Want more details about the reference entity record resource? [Check its endpoints here!](/api-reference.html#Referenceentityrecord)
:::

::: panel-link Want to filter reference entity records by their attribute values? [Check the filtering documentation here!](/documentation/filter.html#by-attribute-values)
:::

## Focus on the reference entity record values

Reference entity record values hold all the information of a reference entity record. In concrete terms, it is the values of the attributes you will find in the record of a reference entity.
Expand Down
48 changes: 48 additions & 0 deletions content/rest-api/filter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1579,6 +1579,54 @@ As a result you will receive the following answer:
}
```

### By attribute values

::: availability versions=SaaS editions=EE

You can filter reference entity records on their attribute values using the `search` query parameter.
For scopable/localizable attributes, you can optionally specify a `channel` and/or `locale` in the filter.
If omitted, the API will try to use the `channel`/`locales` provided in the request.

Supported types and operators:
- text: `=`, `!=`, `CONTAINS`, `DOES NOT CONTAIN`, `STARTS WITH`, `ENDS WITH`, `EMPTY`, `NOT EMPTY`
- number: `=`, `!=`, `<`, `<=`, `>`, `>=`, `EMPTY`, `NOT EMPTY`
- single_option: `IN`, `=`, `EMPTY`, `NOT EMPTY`
- multiple_options: `IN`, `=`, `EMPTY`, `NOT EMPTY`
- reference_entity_single_link: `IN`, `=`, `EMPTY`, `NOT EMPTY`
- reference_entity_multiple_links: `IN`, `=`, `EMPTY`, `NOT EMPTY`

Notes:
- Filtering on attribute type `image` is not supported. The API will return a 422 error.
- Filtering on attribute type `asset_collection` is not supported. The API will return a 422 error.
- Attribute identifiers must match the regex `^[a-zA-Z0-9_]+$`.
- For `reference_entity_single_link` and `reference_entity_multiple_links` attributes, the value used in the filter is the code of the linked reference entity record.

#### Examples

Filter by a text attribute value:

```
/api/rest/v1/reference-entities/brands/records?search={"description":{"operator":"CONTAINS","value":"furniture","locale":"en_US","channel":"ecommerce"}}
```

Filter by a number attribute value:

```
/api/rest/v1/reference-entities/brands/records?search={"creation_year":{"operator":">","value":"1950"}}
```

Filter by an option (single or multiple):

```
/api/rest/v1/reference-entities/designers/records?search={"nationality":{"operator":"IN","value":["french","italian"]}}
```

Filter by a reference entity link (single or multiple):

```
/api/rest/v1/reference-entities/brands/records?search={"designers":{"operator":"IN","value":["starck","dixon"]}}
```

## Filter assets

When requesting a [list of assets via the REST API](/api-reference.html#get_assets), you can apply filters to get only the ones you want and also the kind of information you want in them.
Expand Down