Finding documents (persistent.findDocuments)

You can use persistent.findDocuments to find documents based on a particular document definition.

For documents saved in V1 the function: persistent.findDocumentsV1 can be used.

Syntax

persistent.findDocuments(ddName, queryObject, queryOptions);

Parameters

Parameter	Type	Required	Description
ddName	String or null	Yes	The name of the document definition. If the value is null, BizzStream will use the name of the document from which the script was started.
queryObject	object	Yes	The object with which you can specify the search criteria. This object has to be made in the Mongo query format
queryOptions	Object	No	The options that can be used in the Mongo query

Query options

Query Parameter	Type	Description	Validation Rules
sort	object	Used for the sorting order (default: natural order). This is an object that contains the fields and their sorting order. The value -1 represents a descending sorting order while the value 1 represents an ascending sorting order	Sort values must be either 1 or -1
skip	number	Number of documents to skip at the beginning.	Must be an integer greater than or equal to 0
fields	object	Dictionary of fields to return or exclude. This is an object that contains the fields and an indication of whether the field is included (value 1) or excluded (value 0)	Field projection values must be either 0 or 1
limit	number	Maximum number of documents to return.	Must be an integer between 1 and 800

Return value

An array containing the documents. If no documents can be found, a null value.

If the query object includes any undefined values or is entirely undefined, it will throw an error.

Note: Query options are validated according to the rules specified in the table above. If validation fails, an error will be thrown.

When a document is found it will return an object something like this:

[
  {
    _id: 'i8Dz0cKKp48mcW648ExZ',
    status: 'ready',
    accessGroups: [ [Object], [Object], [Object], [Object] ],
    _documentDefinitionId: 'CghGFDo90qxqKaJI25owl',
    _environmentId: 'maxedy_pizza',
    picture: [ [Object] ],
    externalId: 'external_i6Z3DzmccKKp4WExZ',
    _createdByUserId: '2LhXDMnJ83wfGkXHe',
    _lastModifiedOn: '2025-04-23T10:19:33.573Z',
    _createdOn: '2023-06-23T09:44:35.853Z',
    _lastModifiedByUserId: '1YNEXKYkPnqk52Fzf',
    _hash: 'rqAZfgL8lePNqHTgdI2I70Lub5WoB50m5zj1FPOeviE='
  }
]

Examples

Basic query

The following method allows you to search for documents of the type project for which the projectNr field is equal to 12345.

persistent.findDocuments('project', {"projectNr":"12345"});
console.log('Give me the documents with projectnumber 12345', projectNumber)

Using limit and skip

Limit the number of results and skip the first few documents:

// Get only the first 10 documents
const limitedResults = persistent.findDocuments('project', {"status":"active"}, {limit: 10});

// Skip the first 20 documents and get the next 10
const paginatedResults = persistent.findDocuments('project', {"status":"active"}, {
  skip: 20,
  limit: 10
});

Using fields projection

Include or exclude specific fields from the results:

// Include only specific fields (1 = include, 0 = exclude)
const specificFields = persistent.findDocuments('project', {"status":"active"}, {
  fields: {
    _id: 1,           // Include document ID
    projectNr: 1,     // Include project number
    name: 1,          // Include name
    description: 0    // Exclude description
  }
});

// Exclude specific fields (all other fields will be included)
const excludeFields = persistent.findDocuments('project', {"status":"active"}, {
  fields: {
    _hash: 0,         // Exclude hash
    _createdOn: 0,    // Exclude creation date
    _lastModifiedOn: 0 // Exclude last modified date
  }
});

Using sort

Sort the results by specific fields:

// Sort by project number in ascending order
const sortedResults = persistent.findDocuments('project', {"status":"active"}, {
  sort: {
    projectNr: 1  // 1 = ascending, -1 = descending
  }
});

// Sort by multiple fields
const multiSortedResults = persistent.findDocuments('project', {"status":"active"}, {
  sort: {
    status: 1,     // First sort by status (ascending)
    projectNr: -1  // Then by project number (descending)
  }
});

Combining multiple options

Use multiple query options together:

const complexQuery = persistent.findDocuments('project', {"status":"active"}, {
  fields: {
    _id: 1,
    projectNr: 1,
    name: 1,
    description: 0
  },
  sort: {
    status: 1
  },
  skip: 10,
  limit: 5
});