Object - Query

Type identifier: object:query Category: Object Operations

Description

Queries Records based on filter criteria. Supports complex filtering, pagination, and ordering. Returns matching Records with metadata. Results can be processed, displayed, or passed to downstream nodes.

Input Handles

Input Handle Details

Variable Handles

Input handles are dynamically generated based on the variables configuration:

• Handle ID: Variable's id property
• Type: Defined by the variable's type configuration
• Required: Based on variable's required property
• Notes: Variables are used to populate filter expressions

Output Handles

Output Handle Details

results

• Type: Object (if firstOnly) or Array (if multiple)

• Includes:

  • All Record properties
  • id: Record ID
  • schemaId: Schema ID
  • createdAt: Creation timestamp
  • updatedAt: Last update timestamp
  • createdById: Creator ID
  • updatedById: Last updater ID

• Notes:

  • Returns null if firstOnly and no results
  • File entries are augmented with Record context

Configuration Options

Configuration Details

variables

• Type: Array of variable definitions

• Notes:

  • Each variable creates an input handle
  • Variables are used in filter expressions
  • Built-in spaceIdentityId always available

filter

• Type: Filter object
• Operators: eq, ne, gt, gte, lt, lte, contains, startsWith, endsWith, in, notIn, isNull, isNotNull

• Notes:

  • Supports nested AND/OR logic
  • Property values can be literals or context values
  • Relationship filters supported

limit

• Type: number
• Default: 25
• Minimum: 0
• Maximum: 1000 (hard cap)

• Notes:

  • Values are clamped to the range [0, 1000]. A configured limit of 5000 is silently reduced to 1000; a negative value is clamped to 0.
  • When firstOnly is true, the effective limit is 1 regardless of the configured value.
  • To process more than 1000 Records, use Pagination or Patterns for Large Datasets described below.

Result Limits

The Object - Query node enforces a hard cap on the number of Records a single run can return.

Limit Reference

For result sets larger than ~1000 Records, a single run of the Object - Query node will not return them all. See the patterns below.

Pagination

The Object - Query node supports offset + limit pagination. Both are configured directly on the node.

Patterns for Large Datasets

1. Pagination With offset + limit

Each iteration advances offset by limit; a page with fewer than limit results is the last page.

{
  "type": "object:query",
  "data": {
    "label": "Page through orders",
    "schemaId": "order-schema-uuid",
    "variables": [{ "id": "pageOffset", "type": { "type": "number", "required": true } }],
    "orderBy": "createdAt",
    "order": "asc",
    "limit": 1000,
    "offset": 0
  }
}

The pageOffset variable supplies offset from the surrounding Flow. A page with fewer than limit results is the last page (see Pagination).

2. Filter-Narrow Before Query

Selective filters (properties, time windows, status) can reduce the candidate set so that it fits within 1000 Records.

{
  "type": "object:query",
  "data": {
    "label": "Yesterday's failed orders",
    "schemaId": "order-schema-uuid",
    "filter": {
      "type": "and",
      "filters": [
        {
          "path": "status",
          "type": "property",
          "value": { "type": "literal", "value": "failed" },
          "operator": "eq"
        },
        {
          "path": "createdAt",
          "type": "property",
          "value": { "type": "contextValue", "valueId": "sinceTimestamp" },
          "operator": "gte"
        }
      ]
    },
    "orderBy": "createdAt",
    "order": "desc",
    "limit": 500
  }
}

3. Aggregate With List - Aggregate

A List - Aggregate node can reduce a bounded query's results to a count, sum, or other aggregate. For totals across more than 1000 Records, aggregate across pages (pattern 1).

Behaviour

Execution Flow

1. Resolves all variable values from input handles
2. Populates filter with variable values
3. Matches Records of the configured Schema in the current Space, excluding removed Records
4. Applies filter conditions, ordering, and pagination
5. Augments file entries with context
6. Returns results (single or array)

Error Handling

Examples

Query by ID

{
  "type": "object:query",
  "data": {
    "label": "Get User by ID",
    "schemaId": "user-schema-uuid",
    "variables": [
      {
        "id": "userId",
        "type": { "name": "userId", "type": "string", "required": true }
      }
    ],
    "filter": {
      "path": "id",
      "type": "property",
      "value": { "type": "contextValue", "valueId": "userId" },
      "operator": "eq"
    },
    "firstOnly": true
  }
}

Query With Pagination

{
  "type": "object:query",
  "data": {
    "label": "List Recent Orders",
    "schemaId": "order-schema-uuid",
    "filter": {
      "path": "status",
      "type": "property",
      "value": { "type": "literal", "value": "completed" },
      "operator": "eq"
    },
    "orderBy": "createdAt",
    "order": "desc",
    "limit": 10,
    "offset": 0
  }
}

Search Products With Combined Filters

{
  "type": "object:query",
  "data": {
    "label": "Search Products",
    "schemaId": "product-schema-uuid",
    "variables": [
      { "id": "minPrice", "type": { "type": "number" } },
      { "id": "category", "type": { "type": "string" } }
    ],
    "filter": {
      "type": "and",
      "filters": [
        {
          "path": "price",
          "type": "property",
          "value": { "type": "contextValue", "valueId": "minPrice" },
          "operator": "gte"
        },
        {
          "path": "category",
          "type": "property",
          "value": { "type": "contextValue", "valueId": "category" },
          "operator": "eq"
        },
        {
          "path": "active",
          "type": "property",
          "value": { "type": "literal", "value": true },
          "operator": "eq"
        }
      ]
    },
    "limit": 50
  }
}