Guides

Search

Query, filter, and sort data in Joyfill

Suggest Edits

Some top level API resources support retrieval with search API methods. You can use the search APIs to retrieve your Joyfill data in a flexible manner. Using search is a faster alternative to paginating through all resources. To create a search query, review the Search query language and reference the query fields of the resource.

📘

Important Note: Only documents created after May 30th 2023 are available for query and sort.

Examples

Here are some examples of what you can do with the Search Documents API.

IMPORTANT: Query Template Documents - If you're trying to query documents for a specific template can still follow the same guide below. Instead of retrieving a document in the Getting Started step, you simply need to use the Templates API route to retrieve the template. Retrieving the File ID and FieldID for internal field queries work the same for both templates and documents because they both follow the same object structure.

Getting Started

Before we get started with querying documents data we are going to retrieve a document and grab our target FileID and FieldID. These IDs will be used to query documents based on their internal field data.

//Step 1: Retrieve A Document
const response = await fetch("https://api-joy.joyfill.io/v1/documents/doc_identifier", {
  method: 'GET',
  mode:'cors',
  headers: {
    Authorization: `Bearer ${userAccessToken}`,
    'Content-Type': 'application/json'
  }
});

//Step 2: There are two methods to retrieving the FileID and FieldID
const joyDoc = await response.json();

//Method 1: Using files object
joyDoc.files[0]._id //File ID. 
joyDoc.files[0].pages[0].fields[0].field //FieldID. IMPORTANT: Ensure you use `.field` property.

//Method 2: Using top level fields
joyDoc.fields[0].fileId;
joyDoc.fields[0].fieldId;

Return exact match and sort results

Lookup documents that match the exact internal field value of "joy" and sort by createdOn.

const fileId = '638ca7c8880dfc1bca968be0';
const fieldId = '638ca7c8674374a0508b232a';

const response = await fetch("https://api-joy.joyfill.io/v1/documents/search", {
  method: 'POST',
  mode:'cors',
  headers: {
    Authorization: `Bearer ${userAccessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: {
     	"fields.638ca7c8880dfc1bca968be0.638ca7c8674374a0508b232a.value": "joy"
    },
    sort: {
     	createdOn: -1 
    }
  })
});

Return substring match and sort results

Lookup documents that contain the internal field value of "joy" (case insensitive) and sort by internal field value.


const fileId = '638ca7c8880dfc1bca968be0';
const fieldId = '638ca7c8674374a0508b232a';

const response = await fetch("https://api-joy.joyfill.io/v1/documents/search", {
  method: 'POST',
  mode:'cors',
  headers: {
    Authorization: `Bearer ${userAccessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: {
     	"fields.638ca7c8880dfc1bca968be0.638ca7c8674374a0508b232a.value": {$regex: "joy", $options: "i"}
    },
    sort: {
     	"fields.638ca7c8880dfc1bca968be0.638ca7c8674374a0508b232a.value": -1 
    }
  })
});

Combine Multiple Filters

Lookup documents matching a combination of internal field data and date range. The documents below will contain the value joy and have a createdOn timestamp within the specified 6 day period.


const fileId = '638ca7c8880dfc1bca968be0';
const fieldId = '638ca7c8674374a0508b232a';

const response = await fetch("https://api-joy.joyfill.io/v1/documents/search", {
  method: 'POST',
  mode:'cors',
  headers: {
    Authorization: `Bearer ${userAccessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: {
      "$and": [
        {"fields.638ca7c8880dfc1bca968be0.638ca7c8674374a0508b232a.value": {$regex: "joy", $options: "i"}},
        {"createdOn": {$gt: 1672981200000, $lt: 1685133261338}} //Created over a 6 day period
    	]
    }
  })
});

Search query language

Search Syntax

TypeUsageDescriptionExamples
Exact Matchfield:"value"Exact match operator.name:"joy" returns records where the name is exactly “joy” in a case-sensitive comparison.
Regular Expression Matchfield:{$regex:"value", $options: "i"}Substring and Case Insensitive match operatorname:{$regex: "joy", $options: "i"} returns records where the name contains "joy" in a case-insensitive comparison. Example matches are: "JOY", "joY", "[email protected]", etc.
Not Equal Matchfield:{$ne:"value"}Returns records that don’t match the clausename:{$ne: "joy"} returns records that aren’t equal to "joy"
Greater Than / Less Than Matchfield:{$gt:"value"}, field:{$gte:"value"}, field:{$lt:"value"}, field:{$lte:"value"}Greater than/less than operatorscreatedOn:{$gt: 10} returns records that have a createdOn greater than 10. $gt specifies greater than. $gte specifies greater than or equal to. $lt specifies less than. $lte specifies less than or equal to.
AND$and:[{field:"value1"}, {field:"value2"}]The query returns only records that match both clauses.$and:[{name: "joy"}, {template: "template_000"}]
OR$or:[{field:"value1"}, {field:"value2"}]The query returns records that match either of the clauses$or:[{name: "joy"}, {template: "template_000"}]

Sort query language

Sort Syntax

TypeUsageDescription
Ascending Sortfield:1Returns records sorted in ascending order.
Descending Sortfield:-1Returns records sorted in descending order.

Supported Query and Sort Fields

Query fields for documents

FieldDescriptionValue Type
templateReturns records that match a specified template identifier.String
groupReturns records that match a specified group identifier.String
stageReturns records that match a specified stage.String('draft', 'published')
nameReturns records that match a specified nameString
createdOnReturns records that match a specified createdOn date.Number (millisecond timestamp)
fields.FileID.FieldID.valueReturns records that match a specified field value. You will need to replace the FileID and FieldID with intended targets from your Joyfill Document or Template.Mixed (String, Int, Float, or Boolean)

Updated about 1 year ago