Queries Pagination

Most listing methods in PrivMX Bridge API use pagination and filtering. These mechanisms make browsing large datasets efficient, as pagination controls which subset of data is returned in the response.

Pagination Parameters Structure

The parameters are passed as a single object.

Examples

    const threads = await threadsApi.listThreads(contextId, {
        skip: 0,
        limit: 100,
        sortOrder: "desc",
        queryAsJson: JSON.stringify({
            "#creator": userId,
        }),
    });

Cursor-based pagination with lastId

    const threads = await threadsApi.listThreads(contextId, {
        lastId: "68f7a19d15718c5c040cd519" 
        skip: 0,
        limit: 100,
        sortOrder: "desc",
    });

Filtering Results (queryAsJson Object)

The queryAsJson field allows advanced filtering based on values in an object's public metadata. Use it to specify the records you want to retrieve.

You can only filter using the publicMeta field. While the actual data within your publicMeta can be anything you need and structured however you want, it must be formatted as correct JSON in order for the system to read and query its contents.

Query Basics

Queries rely on fields within publicMeta. For example, consider this object:

{
  "status": "active",
  "role": "admin",
  "score": 42,
  "additionalInfo": {
    "category": "finance",
    "label": "urgent"
  }
}

The simplest query uses an equality check.

Example: Find records where status is "active".

{
  "status": "active"
}

This is a shorthand for using the $eq (equals) operator:

{
  "status": { "$eq": "active" }
}

For more complex comparisons, use operators like $gt (greater than).

Example: Find records where score is greater than 20.

{
  "score": { "$gt": 20 }
}

Advanced Query Examples

Multiple Conditions on a Single Field

Apply several operators to one field to create a range.

Example: Find records where score is greater than 20 and less than 35.

{
  "score": { "$gt": 20, "$lt": 35 }
}

Querying Nested Objects

To reference fields in nested objects, use dot notation (.).

Example: Find records where category inside additionalInfo is "finance".

{
  "additionalInfo.category": "finance"
}

Querying Built-in Fields

Besides public metadata, you can filter based on built-in fields in the document structure. The available fields depend on the document type.

To query a built-in field, prefix its name with a hash symbol (#).

Example: Find documents created by a specific user.

{
  "#creator": "USER_ID_123"
}

Example: Find all documents except for a specific ID.

{
  "#id": {
    "$nin": ["THREAD_ID_TO_EXCLUDE"]
  }
}

Available fields may include:

• id
• userId
• creator
• createDate
• created
• userPubKey
• lastModifier
• lastModificationDate
• users
• messages
• author
• lastEntryDate
• entries
• lastFileDate
• files
• size
• entryKey

Combining Multiple Conditions (Logical AND)

By default, top-level conditions in a query are joined by a logical AND.

Example: Find records where score is greater than 20 and status is "active".

{
  "score": { "$gt": 20 },
  "status": "active"
}

You can also explicitly use the $and operator.

{
  "$and": [
    { "score": { "$gt": 20 } },
    { "status": "active" }
  ]
}

Using the $or Operator

Use $or to find records that meet at least one condition.

Example: Find records where status is "active" or role is "member".

{
  "$or": [
    { "status": "active" },
    { "role": "member" }
  ]
}

Available Operators

Allowed Query Values

Allowed values include String, Number, Boolean, and Null. Do not use objects or arrays, except in $in and $nin.

Logical Operators

Use logical operators to combine multiple conditions.

Field Property Operators

Use these operators for specific metadata fields.