How Query Predicates Work

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, then for all the available predicates, and finally for the predicate options.

Predicate Path Reference

Here are the different paths available when creating your query predicates.

document.type

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.

Copy
      Prismic.Predicates.at('document.type', 'product')
    
Copy
      Predicates::at('document.type', 'product')
    
Copy
      Prismic::Predicates.at("document.type", "product")
    

document.id

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.

Copy
      Prismic.Predicates.at('document.id', 'WGvVEDIAAAcuB3lJ')
    
Copy
      Predicates::at('document.id', 'WGvVEDIAAAcuB3lJ')
    
Copy
      Prismic::Predicates.at("document.id", "WGvVEDIAAAcuB3lJ")
    

document.tag

The document.tag path looks at the tags associated with the document. You can add tags to a document from the document edit screen.

Note that even when querying for one single tag, you need to put the string for the tag inside of an array.

The following predicate would retrieve all of the documents with the tag "featured".

Copy
      Prismic.Predicates.at('document.tags', ['featured'])
    
Copy
      Predicates::at('document.tags', ['featured'])
    
Copy
      Prismic::Predicates.at("document.tags", ["featured"])
    

document.first_publication_date

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 docuement is published and it never changes.

The following predicate would retrieve all the documents that were first published in the year 2017.

Copy
      Prismic.Predicates.year('document.first_publication_date', 2017)
    
Copy
      Predicates::year('document.first_publication_date', 2017)
    
Copy
      Prismic::Predicates.year("document.first_publication_date", 2017)
    

document.last_publication_date

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 2017.

Copy
      Prismic.Predicates.year('document.last_publication_date', 2017)
    
Copy
      Predicates::year('document.last_publication_date', 2017)
    
Copy
      Prismic::Predicates.year("document.last_publication_date", 2017)
    

document

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”.

Copy
      Prismic.Predicates.fulltext('document', 'football')
    
Copy
      Predicates::fulltext('document', 'football')
    
Copy
      Prismic::Predicates.fulltext("document", "football")
    

my.{custom-type}.{field}

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.

Copy
      Prismic.Predicates.at('my.product.price', 100)
    
Copy
      Predicates::at('my.product.price', 100)
    
Copy
      Prismic::Predicates.at("my.product.price", 100)
    

Predicate Reference

at(path, value)

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).

When using the my.{custom-type}.{field} path, this predicate works with the following fields: UID, Key Text, Select, Number, & Date.

Accepted paths: document.type, document.tags, document.id, my.{custom-type}.{field}

Accepted values: single value (for all but document.tags), array of values (only for document.tags)

Examples:

Copy
      Prismic.Predicates.at('document.type', 'product')
Prismic.Predicates.at('document.tags', ['Macaron', 'Cupcake'])
Prismic.Predicates.at('my.product.price', 50)
    
Copy
      Predicates::at('document.type', 'product')
Predicates::at('document.tags', ['Macaron', 'Cupcake'])
Predicates::at('my.product.price', 50)
    
Copy
      Prismic::Predicates.at("document.type", "product")
Prismic::Predicates.at("document.tags", ['Macaron', 'Cupcake'])
Prismic::Predicates.at("my.product.price", 50)
    

not(path, value)

The not predicate checks that the path doesn't match the provided value exactly. It takes a single value as the argument.

When using the my.{custom-type}.{field} path, this works with the following fields: UID, Key Text, Select, Number, & Date.

Accepted paths: document.type, document.tags, document.id, my.{custom-type}.{field}

Accepted value: single value

Copy
      Prismic.Predicates.not('document.type', 'product')
    
Copy
      Predicates::not('document.type', 'product')
    
Copy
      Prismic::Predicates.not("document.type", "product")
    

any(path, values)

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 the my.{custom-type}.{field} path, this predicate works with the following fields: UID, Key Text, Select, Number, & Date.

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.

Accepted paths: document.type, document.tags, document.id, my.{custom-type}.{field}

Accepted value: array of values

Copy
      Prismic.Predicates.any('document.type', ['product', 'blog-post'])
    
Copy
      Predicates::any('document.type', ['product', 'blog-post'])
    
Copy
      Prismic::Predicates.any("document.type", ["product", "blog-post"])
    

in(path, values)

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.

Accepted paths: document.id, my.{custom-type}.uid

Accepted value: array of values

Examples:

Copy
      Prismic.Predicates.in('document.id', ['V9rIvCQAAB0ACq6y', 'V9ZtvCcAALuRUzmO'])
Prismic.Predicates.in('my.page.uid', ['myuid1', 'myuid2'])
    
Copy
      Predicates::in('document.id', ['V9rIvCQAAB0ACq6y', 'V9ZtvCcAALuRUzmO'])
Predicates::in('my.page.uid', ['myuid1', 'myuid2'])
    
Copy
      Prismic::Predicates.in("document.id", ["V9rIvCQAAB0ACq6y", "V9ZtvCcAALuRUzmO"])
Prismic::Predicates.in("my.page.uid", ["myuid1", "myuid2"])
    

fulltext(path, value)

The fulltext predicate provides two capabilities: 1) checking if a certain string is anywhere inside a document (this is what you should use to make your project's search engine feature), or 2) 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, Key Text, UID, & Select. The fulltext search is not case sensitive.

Accepted paths: document, my.{custom-type}.{field}

Accepted value: search terms

Examples:

Copy
      Prismic.Predicates.fulltext('document', 'banana') // one term
Prismic.Predicates.fulltext('document', 'banana apple') // two terms
Prismic.Predicates.fulltext('my.product.title', 'phone') // specific field
    
Copy
      Predicates::fulltext('document', 'banana') // one term
Predicates::fulltext('document', 'banana apple') // two terms
Predicates::fulltext('my.product.title', 'phone') // specific field
    
Copy
      Prismic::Predicates.fulltext("document", "banana") # one term
Prismic::Predicates.fulltext("document", "banana apple") # two terms
Prismic::Predicates.fulltext("my.product.title", "phone") # specific field
    

has(path)

The has predicate checks whether a fragment has a value. Note that this predicate will restrict the results to the custom type implied in the path.

This predicate works on all fields except for Groups and Slices.

Accepted path: my.{custom-type}.{field}

Copy
      Prismic.Predicates.has('my.product.price')
    
Copy
      Predicates::has('my.product.price')
    
Copy
      Prismic::Predicates.has("my.product.price")
    

missing(path)

The missing predicate checks if a fragment doesn't have a value. Note that this predicate will restrict the results to the custom type implied in the path.

This predicate works on all fields except for Groups and Slices.

Accepted path: my.{custom-type}.{field}

Copy
      Prismic.Predicates.missing('my.product.price')
    
Copy
      Predicates::missing('my.product.price')
    
Copy
      Prismic::Predicates.missing("my.product.price")
    

similar(id,value)

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".

id: document ID

Accepted value: the maximum number of documents that a term may appear in to still be considered relevant

Copy
      Prismic.Predicates.similar('VkRmhykAAFA6PoBj', 10)
    
Copy
      Predicates::similar('VkRmhykAAFA6PoBj', 10)
    
Copy
      Prismic::Predicates.similar("VkRmhykAAFA6PoBj", 10)
    

Date & Time based Predicates

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 and Timestamp page.

Number based Predicates

There are a few predicates that are specifically used for the Number field. You can read more about them on the Number page.

Predicate Options Reference

pageSize

The pageSize option defines the maximum number of documents that the API will return for your query. Default is 20, max is 100.

value: page size (between 1 and 100)

Copy
      { pageSize : 100 }
    
Copy
      [ 'pageSize' => 100 ]
    
Copy
      { "pageSize" => 100 }
    

page

The page option defines the pagination for the result of your query. Defaults to "1", corresponding to the first page.

value: page index

Copy
      { page : 2 }
    
Copy
      [ 'page' => 2 ]
    
Copy
      { "page" => 2 }
    

orderings

The orderings option orders the results by the specified field(s). You can specify as many fields as you want.

It will automatically order the field from lowest to greatest. Use "desc" next to the field name to instead order it from greatest to lowest. Both cases are shown below in the examples.

It is also possible to order documents by their first and last publication dates. The first publication date is the date that the document was originally published for the first time. The last publication date is the most recent date that the document has been published after editing. There is an example of each of these in the examples below.

value: content field, first publication date, or last publication date

Examples

Copy
      { orderings : '[my.product.price]' }
{ orderings : '[my.product.price desc, my.product.title]' }
{ orderings : '[document.first_publication_date]' }
{ orderings : '[document.last_publication_date]' }
    
Copy
      [ 'orderings' => '[my.product.price]' ]
[ 'orderings' => '[my.product.price desc, my.product.title]' ]
[ 'orderings' => '[document.first_publication_date]' ]
[ 'orderings' => '[document.last_publication_date]' ]
    
Copy
      { "orderings" => "[my.product.price]" }
{ "orderings" => "[my.product.price desc, my.product.title]" }
{ "orderings" => "[document.first_publication_date]" }
{ "orderings" => "[document.last_publication_date]" }
    

after

The after option can be used along with the orderings option. It will remove all the documents except for those after the specified document in the list.

To clarify, let’s say you have a query that return the following documents in this order:

V9Zt3icAAAl8Uzob (Page 1)
PqZtvCcAALuRUzmO (Page 2)
VkRmhykAAFA6PoBj (Page 3)
V4Fs8rDbAAH9Pfow (Page 4)
G8ZtxQhAALuSix6R (Page 5)
Ww9yuAvdAhl87wh6 (Page 6)

If you add the after option and specify page 3, “VkRmhykAAFA6PoBj”, your query will return the following:

V4Fs8rDbAAH9Pfow (Page 4)
G8ZtxQhAALuSix6R (Page 5)
Ww9yuAvdAhl87wh6 (Page 6)

By reversing the orderings in your query, you can use this same method to retrieve all the documents before the specified document.

This option is useful when creating a navigation for a blog.

value: document id

Copy
      { after : 'VkRmhykAAFA6PoBj' }
    
Copy
      [ 'after' => 'VkRmhykAAFA6PoBj' ]
    
Copy
      { "after" => "VkRmhykAAFA6PoBj" }
    

fetch

The fetch option is used to make queries faster by only retrieving the specified field(s).

value: fields to retrieve

Examples

Copy
      { fetch : 'product.title' }
{ fetch : ['product.title', 'product.price'] }
    
Copy
      [ 'fetch' => 'product.title' ]
[ 'fetch' => 'product.title, product.price']
    
Copy
      { "fetch" => "product.title" }
{ "fetch" => "product.title, product.price" }
    

The fetchLinks option is used when the queried document links to another document in the repository with the Link field. This option allows you to retrieve simple fields from the linked document.

Note that this only works with basic fields such as Text, Number or Date. It is not possible to retrieve Rich Text fragments from the linked document using this field.

The value you enter for the fetchLinks option needs to take the following format: 'custom-type.field-name'

The custom type you use needs to be the custom type API-ID of the linked document. The field name needs to be the API-ID of the field you wish to retrieve from that document.

To view a complete example of how this option works check out the Fetch Linked Document Fields page.

value: 'custom-type.field-name'

Examples

Copy
      { fetchLinks : 'author.full_name' }
{ fetchLinks : ['author.first-name', 'author.last-name'] }
    
Copy
      [ 'fetchLinks' => 'author.full_name' ]
[ 'fetchLinks' => 'author.first-name, author.last-name' ]
    
Copy
      { "fetchLinks" => "author.full_name" }
{ "fetchLinks" => "author.first-name, author.last-name" }