Query API Overview

The Informer Query API provides comprehensive endpoints for creating, managing, and executing queries. Queries are parameterized SQL or language-specific definitions that can be run to generate datasets. All routes are prefixed with /api.

Features

• CRUD Operations - Create, read, update, and delete queries
• Drafts & Versioning - Create draft copies for safe editing without affecting production
• Execution - Run queries to generate embedded datasets with progress tracking
• Benchmarking - Test query performance with configurable benchmark runs
• Fields & Parameters - Manage query fields and input parameters
• Query Languages - Support for multiple query languages (SQL, i5-QL, etc.)
• Templates - Reusable query templates for common patterns
• Sharing & Permissions - Team-based access control with granular permissions
• Comments - Collaborate with inline comments on queries
• Tags & Favorites - Organize and bookmark queries
• Export - Export query results to multiple formats

Query Structure

Queries in Informer consist of:

Property	Type	Description
id	UUID	Unique identifier
naturalId	string	Human-readable ID (slug-based or UUID)
name	string	Query display name
description	string	Query purpose and details
language	string	Query language (e.g., sql, i5-ql)
datasourceId	UUID	Associated datasource connection
payload	object	Language-specific query definition
inputs	object	Input parameter definitions
flow	array	Multi-step transformation pipeline
fields	object	Field metadata and formatting
settings	object	Query-specific settings
embedded	boolean	Whether query is embedded in a dataset
shared	boolean	Whether query is shared with others

Authentication

All Query API endpoints require authentication via session cookies or API tokens. Most endpoints verify query permissions before allowing access.

Common Permission Patterns

• Read access - View query structure and metadata
• Write permission - Required for query:write (create, update, delete, field changes)
• Run permission - Required for query:run (execute queries, generate datasets)
• Copy permission - Required for query:copy (copy queries)
• Share permission - Required for query:share (manage access and shares)

Query Languages

Informer supports multiple query languages:

Language	Description
sql	Standard SQL queries with parameter support
i5-ql	Informer Query Language - visual query builder
flow	Multi-step transformation pipeline

Each language has its own payload structure and capabilities. Use GET /api/query-languages to discover available languages and their features.

Embedded vs. Ad-hoc Queries

Queries can be:

• Ad-hoc (embedded: false) - Standalone queries that can be run to generate temporary datasets
• Embedded (embedded: true) - Queries embedded within a dataset definition, run when the dataset is refreshed

Embedded queries cannot be run directly - they must be executed through their parent dataset.

Drafts & Versioning

Queries support draft mode for safe editing:

1. Create draft - POST /api/queries/{id}/_edit
2. Modify draft - Make changes to draft without affecting production
3. Commit draft - POST /api/queries/{id}/draft/_commit to publish changes

Committing a draft updates the original query and optionally clears all user settings and cached data.

Execution Workflow

Running a query creates or updates an embedded dataset:

POST /api/queries/{id}/_run
{
  "params": { "startDate": "2024-01-01" }
}

This process:

1. Creates or finds an embedded dataset for the query + user
2. Sets dataset TTL based on tenant settings
3. Refreshes the dataset with new parameters
4. Returns the populated dataset

Common Query Parameters

Many list endpoints support:

Parameter	Type	Default	Description
q	string	-	Full-text search query
sort	string	-	Field to sort by (prefix with - for descending)
start	integer	0	Pagination offset
limit	integer	30	Number of results per page
datasource	string	-	Filter by datasource ID

Error Responses

Standard HTTP status codes:

• 200 - Success
• 400 - Bad request (validation error, cannot run embedded query)
• 403 - Forbidden (insufficient permissions)
• 404 - Resource not found
• 409 - Conflict (duplicate, constraint violation)
• 500 - Internal server error

Error responses include:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions to modify query"
}

Long-Running Operations

Several endpoints support long-running operations with progress tracking:

• POST /api/queries/{id}/_run - Run query and generate dataset
• POST /api/queries/{id}/_benchmark - Benchmark query performance
• POST /api/queries - Create query with initial data

These endpoints accept a progress parameter in the payload for progress updates.

Next Steps

Explore the specific endpoint categories:

• Core CRUD - Basic query operations
• Drafts & Versioning - Draft workflow
• Execution - Run queries and generate datasets
• Fields & Parameters - Field and input management
• Query Languages - Language discovery and templates
• Sharing - Access control
• Comments - Query discussions
• Tags & Favorites - Organization
• Ownership - Owner management
• Datasets & Jobs - Associated resources