Here you will find everything you need to learn how the query predicates work. You'll find the descriptions first for all the predicate paths and then for all the available predicates.
Here are the different paths available when creating your query predicates.
The document.type path is the custom type of the document. You would search this path with the API ID of the custom type you are looking for.
In the example below, the API ID of the custom type is "product". This would retrieve all the documents of that custom type.
Predicates::at('document.type', 'product')
The document.id path is the id of the document. This is a unique ID automatically assigned to every document when it is created. It looks something like this: WGvVEDIAAAcuB3lJ
The following example retrieves the one document with that ID.
Predicates::at('document.id', 'WGvVEDIAAAcuB3lJ')
The document.tags path looks at the tags associated with the document. You can add tags to a document from the document edit screen.
The following predicate would retrieve all of the documents with the tag "featured".
Predicates::at('document.tags', ['featured'])
Note that even when querying for one single tag, you need to put the string for the tag inside of an array.
The document.first_publication_date path is the date and time that the document was first published. The value for this field path is filled the first time the document is published and it never changes.
The following predicate would retrieve all the documents that were first published in the year 2020.
Predicates::year('document.first_publication_date', 2020)
The document.last_publication_date path is the date and time that the document was last published. The value for this field path is updated every time the document is edited and re-published.
The following predicate would retrieve all the documents that were published or updated in the year 2020.
Predicates::year('document.last_publication_date', 2020)
The document path is used only with the fulltext predicate described below. This allows you to search an entire document for a defined word, such as "football".
Predicates::fulltext('document', 'football')
This path allows you to query a specific field in a custom type. For {custom-type} you need to use the API ID of the custom type you want to query. For {field} you need to use the API ID of the specific field in the custom type that you need.
The example below searches the "price" field in the "product" custom type.
Predicates::at('my.product.price', 100)
To use the predicates as shown below, you must make sure to include the Predicates class.
use Prismic/Predicates;
Here are descriptions of all the available predicates.
The at predicate checks that the path matches the described value exactly. It takes a single value for a field or an array (only for tags).
Predicates::at( $path, $value )
| Property | Description |
|---|---|
$pathaccepted paths |
document.type document.tags document.id my.{custom-type}.{field} |
$valueaccepted values |
single value (for all but document.tags) array of values (only for document.tags) |
my.{custom-type}.{field}accepted fields |
UID Key Text Select Number Date Boolean |
Examples:
Predicates::at('document.type', 'product')
Predicates::at('document.tags', ['Macaron', 'Cupcake'])
Predicates::at('my.product.price', 50)
The not predicate checks that the path doesn't match the provided value exactly. It takes a single value as the argument.
Predicates::not( $path, $value )
| Property | Description |
|---|---|
$pathaccepted paths |
document.type document.tags document.id my.{custom-type}.{field} |
| $value |
Single value |
my.{custom-type}.{field}accepted fields |
UID Key Text Select Number Date Boolean |
Example:
Predicates::not('document.type', 'product')
The any predicate takes an array of values. It works exactly the same way as the at operator, but checks whether the fragment matches any of the values in the array.
When using this predicate with the ID or UID field, it will not necessarily return the documents in the same order as the passed array.
Predicates::any( $path, $values )
| Property | Description |
|---|---|
$pathaccepted paths |
document.type document.tags document.id my.{custom-type}.{field} |
$valuesarray |
Array of values |
my.{custom-type}.{field}accepted fields |
UID Key Text Select Number Date |
Example:
Predicates::any('document.type', ['product', 'blog-post'])
The in predicate is used specifically to retrieve an array of documents by their IDs or UIDs. This predicate is much more efficient at this than the any predicate.
This returns the documents in the same order as the passed array.
Predicates::in( $path, $values )
| Property | Description |
|---|---|
$pathaccepted paths |
document.id my.{custom-type}.uid |
$valuesarray |
Array of IDs or UIDs |
Examples:
Predicates::in('document.id', ['V9rIvCQAAB0ACq6y', 'V9ZtvCcAALuRUzmO']) // IDs
Predicates::in('my.page.uid', ['myuid1', 'myuid2']) // UIDs
The fulltext predicate provides two capabilities
- Checking if a certain string is anywhere inside a document (this is what you should use to make your project's search engine feature)
- Checking if the string is contained inside a specific custom type’s Rich Text or Key Text fragment.
You can search a document or a text fragment for either just one term or for multiple terms. To search for more than one term, put all the terms into a string with spaces between them as shown in the examples below.
The full document search and specific field search works on the following fields:
- Rich Text
- Title
- Key Text
- UID
- Select
Note that the Fulltext search is not case sensitive.
Predicates::fulltext( $path, $value )
| Property | Description |
|---|---|
$pathaccepted paths |
document my.{custom-type}.{field} |
$valuestring |
Search terms |
Examples:
Predicates::fulltext('document', 'banana') // one term
Predicates::fulltext('document', 'banana apple') // two terms
Predicates::fulltext('my.product.title', 'phone') // specific field
The has predicate checks whether a fragment has a value. It will return all the documents of the specified type that contain a value for the specified field.
Note that this predicate will restrict the results to the custom type implied in the path.
Predicates::has( $path )
| Property | Description |
|---|---|
$pathaccepted path |
my.{custom-type}.{field} |
my.{custom-type}.{field}accepted fields |
All fields except for Groups and Slices |
Example:
Predicates::has('my.product.price')
The missing predicate checks if a fragment doesn't have a value. It will return all the documents of the specified type that do not contain a value for the specified field.
Note that this predicate will restrict the results to the custom type implied in the path.
Predicates::missing( $path )
| Property | Description |
|---|---|
$pathaccepted path |
my.{custom-type}.{field} |
my.{custom-type}.{field}accepted fields |
All fields except for Groups and Slices |
Example:
Predicates::missing('my.product.price')
The similar predicate takes the ID of a document, and returns a list of documents with similar content. This allows you to build an automated content discovery feature (for example, a "Related posts" section).
Also, remember that you can combine it with other predicates. Therefore not only could you search for "similar blog posts," but you could refine that to search for "similar blog posts that mention chocolate".
Predicates::similar( $id, $value )
| Property | Description |
|---|---|
$idstring |
The document ID |
$valueinteger |
The maximum number of documents that a term may appear in to still be considered relevant |
Example:
Predicates::similar('VkRmhykAAFA6PoBj', 10)
The near predicate checks that the value in the path is within the radius of the given coordinates.
This predicate will only work for a GeoPoint field.
Note that the measure of distance used for the radius is in km.
The near predicate will order the results from nearest to farthest from the given coordinates.
Predicates::near( $path, $latitude, $longitude, $radius )
| Property | Description |
|---|---|
$pathaccepted path |
my.{custom-type}.{field} |
$latitudefloat |
Latitude of the center of the search area |
$longitudefloat |
Longitude of the center of the search area |
$radiusfloat |
Radius of search in kilometers |
Example:
Predicates::near('my.restaurant.location', 9.656896299, -9.77508544, 10)
There are a few predicates that are specifically used for the Number field.
Note that when using any of these predicates, you will limit the results of the query to the specified custom type.
The lt predicate checks that the value in the number field is less than the value passed into the predicate.
This is a strict less-than operator, it will not give values equal to the specified value.
Predicates::lt( $path, $value )
| Property | Description |
|---|---|
$pathaccepted path |
my.{custom-type}.{field} |
$valuefloat |
Number value |
Examples:
Predicates::lt('my.instructions.numberOfSteps', 10)
Predicates::lt('my.product.price', 49.99)
The gt predicate checks that the value in the number field is greater than the value passed into the predicate.
This is a strict greater-than operator, it will not give values equal to the specified value.
Predicates::gt( $path, $value )
| Property | Description |
|---|---|
$pathaccepted path |
my.{custom-type}.{field} |
$valuefloat |
Number value |
Examples:
Predicates::gt('my.rental.numberOfBedrooms', 2)
Predicates::gt('my.product.price', 9.99)
The inRange predicate checks that the value in the path is within the two values passed into the predicate.
This is an inclusive search, it will include values equal to the upper and lower limits.
Predicates::inRange( $path, $lowerLimit, $upperLimit )
| Property | Description |
|---|---|
$pathaccepted paths |
my.{custom-type}.{field} |
$lowerLimitfloat |
Lower limit of the range |
$upperLimitfloat |
Upper limit of the range |
Examples:
Predicates::inRange('my.album.track-count', 7, 10)
Predicates::inRange('my.product.price', 9.99, 49.99)
There are a number of predicates that are specifically used for the Date and Timestamp fields. You can read more about them on the Date & Time based Predicate Reference page.