SDK Quick Query Helper Functions

In many of our development kits for prismic.io, we’ve included helper functions to make creating certain queries quicker and easier. This page provides the description and examples for each of the helper function.

Helper Function Reference

getByUID( custom-type, uid, options )

The getByUID function is used to query the specified custom type by a certain uid. This requires that the custom type of the document contains the UID field.

This function will only ever retrieve one document as there can only be one instance of a given uid for each custom type.

custom-type: Required. A string that specifies the API ID of the custom type you are searching for.
uid: Required. A string that specifies the uid of the document you want.
options: Optional. An object with option parameters and values.

Here is an example that queries a document of the type “page” by its uid “about-us”.

Copy
      api.getByUID('page', 'about-us').then(function(pageContent) {
    // pageContent contains the document content
});
    
Copy
      $pageContent = $api->getByUID('page', 'about-us');
// $pageContent contains the document content
    
Copy
      page_content = api.getByUID("page", "about-us")
# page_content contains the document content
    

Here is an example with options.

Copy
      var options = { fetch : 'page.title' };
api.getByUID('page', 'about-us', options).then(function(pageContent) {
    // pageContent contains the document content
});
    
Copy
      // This currently isn't supported in the php kit
    
Copy
      options = { "fetch" => "page.title" }
page_content = api.getByUID("page", "about-us", options)
# page_content contains the document content
    

getByID( id, options )

The getByID function is used to query a certain document by its id. Every document is automatically assigned a unique id when it is created. The id will look something like this: ‘WAjgAygABN3B0a-a’.

This function will only ever retrieve one document as each document has a unique id value.

id: Required. A string that specifies the id of the document you want.
options: Optional. An object with option parameters and values.

Here is an example that queries a document by its id “WAjgAygABN3B0a-a”.

Copy
      api.getByID('WAjgAygABN3B0a-a').then(function(productContent) {
    // productContent contains the document content
});
    
Copy
      $productContent = $api->getByID('WAjgAygABN3B0a-a');
// $productContent contains the document content
    
Copy
      product_content = api.getByID("WAjgAygABN3B0a-a")
# product_content contains the document content
    

Here is an example with options.

Copy
      var options = { fetch : 'product.title'};
api.getByID('WAjgAygABN3B0a-a', options).then(function(productContent) {
    // productContent contains the document content
});
    
Copy
      // This currently isn't supported in the php kit
    
Copy
      options = { "fetch" => "product.title" }
product_content = api.getByID("WAjgAygABN3B0a-a", options)
# product_content contains the document content
    

getByIDs( ids, options )

The getByIDs function is used to query multiple documents by their ids. This will return the documents in the same order specified in the array, unless options are added to sort them otherwise.

ids: Required. An array of strings with the ids of the documents you want.
options: Optional. An object with option parameters and values.

Here is an example that queries multiple documents by their ids.

Copy
      var ids = ['WAjgAygAAN3B0a-a', 'WC7GECUAAHBHQd-Y', 'WEE_gikAAC2feA-z'];
api.getByIDs(ids).then(function(content) {
    // content is the response object, content.results holds the documents
});
    
Copy
      $ids = ['WAjgAygAAN3B0a-a', 'WC7GECUAAHBHQd-Y', 'WEE_gikAAC2feA-z'];
$content = $api->getByIDs($ids);
// $content contains the response object, $content->getResults() holds the documents
    
Copy
      ids = [ "WAjgAygAAN3B0a-a", "WC7GECUAAHBHQd-Y", "WEE_gikAAC2feA-z" ]
content = api.getByIDs(ids)
# content is the response object, content.results holds the documents
    

Here is an example with options that sort the documents by their titles.

Copy
      var ids = ['WAjgAygAAN3B0a-a', 'WC7GECUAAHBHQd-Y', 'WEE_gikAAC2feA-z'];
var options = { orderings : '[page.title]' };
api.getByIDs(ids, options).then(function(content) {
    // content is the response object, content.results holds the documents
});
    
Copy
      // This currently isn't supported in the php kit
    
Copy
      ids = [ "WAjgAygAAN3B0a-a", "WC7GECUAAHBHQd-Y", "WEE_gikAAC2feA-z" ]
options = { "orderings" => "[page.title]" }
content = api.getByIDs(ids, options)
# content is the response object, content.results holds the documents
    

getSingle( custom-type, options )

The getSingle function is used to query the document of a Single custom type. Single custom types only allow for the creation of one document of that type.

This will only ever retrieve one document.

custom-type: Required. A string that specifies the API ID of the single custom type you are searching for.
options: Optional. An object with option parameters and values.

Here is an example that retrieves the document of the Single type “navigation”.

Copy
      api.getSingle(‘navigation’).then(function(navContent) {
    // navContent contains the document content
});
    
Copy
      $navContent = $api->getSingle('navigation');
// $navContent contains the document content
    
Copy
      nav_content = api.getSingle("navigation")
# nav_content contains the document content