How to Query the API with .NET
Prismic natively supports Custom types. Custom types allow you to define and configure fields for your content. Define custom types for pages, posts, events, authors, products, places, …
A productive way to build pages with Prismic, is to follow an iterative cycle of defining fields for your custom type, querying its content, and then integrating it into templates.
Queries allow you to retrieve content to be displayed in your pages.
Queries in Prismic are based on predicates. Some predicates apply to any custom type, and some are field-specific. You can also combine multiple predicates to express your query.
Here is an example query for retrieving a basic page through its UID:
// String uid comes from the querystring
Document document = api.GetByUID("basic-page", uid);
The following example retrieves all blog posts:
Response response = api.query(Predicates.At("document.type", "blog-post"))
.PageSize(10)
.Orderings("my.blog-post.date desc")
.Submit();
A full-text search on all blog posts is done combining two predicates:
Response response = api.Query(
Predicates.At("document.type", "blog-post"),
Predicates.Fulltext("document", terms) // terms is a String
).Submit();
IList<Document> documents = response.Results;
Pagination of API Results
When querying a Prismic repository, your results will be paginated. By default, there are 20 documents per page in the results. You can read more about how to manipulate the pagination below with the query options.
The At operator is the equality operator, checking that the fragment matches the described value exactly.
It takes a value for a field or an array (only for tags).
path
document.type
document.tags
my.{type}.{field}
value
single value
examples
At("document.type", "product")
At("document.tags", ["Macaron", "Cupcake"])
At("my.articles.gender", "male")
The Not operator is the different operator, checking that the fragment doesn't match the described value exactly.
It takes a value for a field.
path
document.type
my.{type}.{field}
value
single value
example
Not("document.type", "product")
The Any operator takes an array of strings as a value. It works exactly the same way as the at operator, but checks whether the fragment matches either one of the values in the array. You can use it with all fragment types.
path
document.type
my.{type}.{field}
values
array of values
example
Any("document.type", ["product", "blog-post"])
The In operator is used to retrieve documents using an Array of IDs or UIDs. This operator is much more performant than the any operator. This operator is more performant than any to query document by UID or ID. This operator return the documents in the same order as the passed Array.
path
document.type
my.{type}.{field}
values
array of values
example
In("document.uid, ["myuid1", "myuid2"])
The Fulltext operator provides two capabilities: either you want to check if a certain string is anywhere inside a document (this is what you should use to make your project's search engine feature), or if the string is contained inside a specific document's structured text fragment. In the example you want to search the term banana in the document
If you want to check in a given structured text fragment you will use something like the second example.
path
document
my.{type}.{field}
value
search terms
example
Fulltext("document", "banana")
Fulltext("my.product.title", "banana")
path
my.{type}.{field}
example
Has('my.product.price')
The Missing operator check if a fragment doesn't have a value. Note that the missing operator will restrict the results to the type implied in the fragment path.
path
my.{type}.{field}
example
Missing('my.product.price')
The Similar operator is especially smart, since it takes an ID of a document, and returns a list of documents whose contents are similar. This allows to build an automated content discovery feature (for instance, a "Related posts" block) at almost no cost.
Also, remember that you can combine it with other predicates, and search for the "similar blog posts" for instance, of even the "similar blog posts that mention chocolate".
id
document ID
value
the maximum count of documents that a term may appear in to be still considered relevant
example
similar("VkRmhykAAFA6PoBj", 10)
description
The PageSize options define the maximum of document that the API will return for your query. Default is 20, max is 100.
value
page size
example
PageSize(3)
description
The page options define the pagination for the result of your query. Defaults to "1", corresponding to the first page.
value
page index
example
Page(2)
description
Order result by fields. You can specify as many fields as you want, in order to address all of the documents you are querying or if you have the same value on a given field. Use "desc" next to the field name, to order it from greatest to lowest.
values
fields
example
Orderings("[my.product.price desc, my.product.price.title]")
description
Query documents after a specific document. By reversing the ordering, you can query for previous documents. Useful when creating navigation for a blog.
value
document id
example
After("VkRmhykAAFA6PoBj")
description
Additional fields to retrieve in LinkDocument fragments. The LinkDocument can then be queried like a Document. Note that this only works with basic fields such as Text, Number or Date. It is not possible to retrieve StructuredText fragments from linked document using this field.
value
fields
example
FetchLinks([author.full_name, author.first_name])
description
fetch only specific fields
value
fields to retrieve
example
Fetch(["author.full_name", "author.first_name"])