PocketBase Custom icon

PocketBase Custom

Work with PocketBase records
Join our community

Actions8

Overview

This node enables querying multiple tables (collections) from a PocketBase backend in a single operation. It is useful when you need to fetch related or disparate data sets simultaneously without making multiple separate requests. For example, you might want to retrieve user records from one table and their associated orders from another, then optionally merge these results based on a common field.

The "Multi-Table Query" operation allows defining multiple queries with filters, fields selection, relation expansions, and limits per table. It also supports options to merge the results into a single list by a specified field, removing duplicates if desired.

Practical scenarios include:

  • Aggregating data from several collections for reporting or dashboards.
  • Fetching related entities across tables with expanded relations.
  • Combining query results into a unified dataset keyed by a unique identifier.

Properties

Name Meaning
Tables Define multiple tables to query. Each table entry includes:
- Collection Name The name of the collection/table to query.
- Filter Filter criteria for this table, e.g., email = "test@example.com".
- Expand Relations Comma-separated list of relations to expand, e.g., turma,turma.colegio.
- Fields Comma-separated list of fields to return; leave empty to return all fields.
- Limit Maximum number of results to return for this table (minimum 1).
Options Additional options for the multi-table query:
- Merge Results Boolean flag indicating whether to merge results from all tables based on a common field.
- Merge Field Field name used for merging results, typically a unique identifier like id. Only shown if "Merge Results" is true.
- Remove Duplicates Boolean flag to remove duplicate entries when merging results. Only shown if "Merge Results" is true.

Output

The output JSON structure depends on whether merging is enabled:

  • If merging is disabled (mergeResults false):

    {
  "merged": false,
  "tables": ["table1", "table2", ...],
  "results": {
    "table1": [ /* array of records from table1 */ ],
    "table2": [ /* array of records from table2 */ ],
    ...
  }
}

    Each key in results corresponds to a queried table name, containing an array of record objects.

  • If merging is enabled (mergeResults true):

    {
  "merged": true,
  "mergeField": "id",
  "count": 123,
  "results": [
    {
      /* merged record object */,
      "sourceTables": ["table1", "table2"]
    },
    ...
  ]
}

    The results array contains merged records keyed by the specified mergeField. Each record includes a sourceTables array listing which tables contributed to that record. Duplicate entries can be removed based on configuration.

No binary data output is produced by this operation.

Dependencies

  • Requires a valid PocketBase backend URL and authentication credentials:
    • Either email/password for admin authentication, or
    • An API token for token-based authentication.
  • The node uses the official pocketbase JavaScript SDK (dynamically imported).
  • Credentials must be configured in n8n with the necessary URL and authentication details.

Troubleshooting

  • Authentication errors:
    Errors like "Authentication failed - No token available" or "PocketBase authentication failed" indicate invalid or missing credentials. Verify the email/password or API token and ensure the PocketBase server URL is correct.

  • Filter syntax issues:
    Filters must follow PocketBase API syntax. Invalid filter expressions may cause query failures. Consult PocketBase documentation for supported filter formats.

  • Relation expansion warnings:
    If some requested expansions fail, a warning is logged mentioning which relations could not be expanded. This often relates to API view rules or permissions on related collections.

  • Merging duplicates:
    When merging results, if unexpected duplicates appear, check the mergeField correctness and the removeDuplicates option.

  • Empty or missing results:
    Ensure the collection names are correct and that the filters do not exclude all records.

Links and References

Discussion