Query Predicates Reference in Javascript

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.

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

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

document.tags

The document.tags 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'])

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)

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)

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

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)

Predicate Reference

at

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

Copy
Prismic.Predicates.at( path, value )

path

accepted paths

document.type
document.tags
document.id
my.{custom-type}.{field}

value

accepted 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

Examples:

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

not

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

Copy
Prismic.Predicates.not( path, value )

path

accepted paths

document.type
document.tags
document.id
my.{custom-type}.{field}

value

accepted value

single value

my.{custom-type}.{field}

accepted fields

UID
Key Text
Select
Number
Date

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

any

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.

Copy
Prismic.Predicates.any( path, values )

path

accepted paths

document.type
document.tags
document.id
my.{custom-type}.{field}

values

accepted value

array of values

my.{custom-type}.{field}

accepted fields

UID
Key Text
Select
Number
Date

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

in

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.

Copy
Prismic.Predicates.in( path, values )

path

accepted paths

document.id
my.{custom-type}.uid

values

accepted value

array of values

Examples:

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

fulltext

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

Copy
Prismic.Predicates.fulltext( path, value )

path

accepted paths

document
my.{custom-type}.{field}

value

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

has

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.

Copy
Prismic.Predicates.has( path )

path

accepted path

my.{custom-type}.{field}

my.{custom-type}.{field}

accepted fields

All fields except for Groups and Slices.

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

missing

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.

Copy
Prismic.Predicates.missing( path )

path

accepted path

my.{custom-type}.{field}

my.{custom-type}.{field}

accepted fields

All fields except for Groups and Slices.

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

similar

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

Copy
Prismic.Predicates.similar( id, value )

id

string

document ID

value

integer

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

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

near

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.

Copy
Prismic.Predicates.near( path, latitude, longitude, radius )

path

accepted paths

my.{custom-type}.{field}

latitude

number

Latitude of the center of the search area

longitude

number

Longitude of the center of the search area

radius

number

Radius of search in kilometers

Example:

Copy
Prismic.Predicates.near('my.restaurant.location', 9.656896299, -9.77508544, 10)

Number based Predicates

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.

lt (Less than)

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.

Copy
Prismic.Predicates.lt( path, value )

path

accepted path

my.{custom-type}.{field}

value

number

number value

Examples:

Copy
Prismic.Predicates.lt('my.instructions.numberOfSteps', 10)
Prismic.Predicates.lt('my.product.price', 49.99)

gt (Greater than)

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.

Copy
Prismic.Predicates.gt( path, value )

path

accepted path

my.{custom-type}.{field}

value

number

number value

Examples:

Copy
Prismic.Predicates.gt('my.rental.numberOfBedrooms', 2)
Prismic.Predicates.gt('my.product.price', 9.99)

inRange

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.

Copy
Prismic.Predicates.inRange( path, lowerLimit, upperLimit )

path

accepted path

my.{custom-type}.{field}

lowerLimit

number

Lower limit of the range

upperLimit

number

Upper limit of the range

Examples:

Copy
Prismic.Predicates.inRange('my.album.track-count', 7, 10) 
Prismic.Predicates.inRange('my.product.price', 9.99, 49.99)

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 & Time based Predicate Reference page.