Drafts & Versioning
Create and manage draft copies of a Query for safe editing without affecting the live Query or its cached data.
Each user gets their own draft of a given Query, so several designers can
experiment in parallel. A draft is itself a Query row: its editingId points at
the original, its ownerId is the caller, and its name is the original name
plus the " (Draft)" suffix.
In every route below, {id} is the original Query. It is resolved by the
query.lookup server method through the read_access scope, so an id the caller
may not see answers a clean 404. The id accepts either the primary-key UUID or
the ownerId:slug natural id.
The write routes (_edit, PUT, DELETE, _commit) require
permission.query.write (the caller is a designer on a non-embedded Query).
Draft Workflow
- Create a personal draft copy of the Query (
POST .../_edit). - Make changes to the draft (
PUT .../draft) without affecting the original. - Commit the draft to update the original Query (
POST .../draft/_commit). - Discard the draft if the changes are unwanted (
DELETE .../draft).
POST /api/queries/{id}/_edit
Create or retrieve the caller's draft copy of a Query.
Authentication: Required
Permission: permission.query.write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | UUID or ownerId:slug natural id of the original Query |
Response:
Idempotent find-or-create: if a draft already exists for the caller it is
returned as-is, otherwise a new draft is created in a transaction. The handler
returns the draft Query directly with 200 (it does not use .created(), so
the status is 200, not 201). The draft carries an editingId pointing at the
original, an ownerId of the caller, and a name ending in " (Draft)".
Create or retrieve a draftPOST /api/queries/00000000-0000-4000-8000-000000000001/_edit
POST /api/queries/{id}/_edit creates (or returns the existing) personal draft copy of a query for safe editing. Requires permission.query.write (isDesigner on a non-embedded query). Idempotent: a second call by the same user returns the same draft. The draft is a Query row whose `editingId` points at the original, `ownerId` is the caller, and `name` is the original name + " (Draft)". The handler returns the draft directly with a 200 (it does NOT use .created()/201).
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit/_export"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/_edit/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/input-templates{?dataType,wildcard}",
"templated": true
}
},
"naturalId": "admin:orders-by-region-draft",
"fields": {
"OrderID": {
"name": "OrderID",
"label": "Order",
"fieldId": null,
"dataType": "double",
"position": 0
},
"CustomerID": {
"name": "CustomerID",
"label": "Customer",
"fieldId": null,
"dataType": "keyword_text",
"position": 1
},
"EmployeeID": {
"name": "EmployeeID",
"label": "Employee",
"fieldId": null,
"dataType": "double",
"position": 2
},
"OrderDate": {
"name": "OrderDate",
"label": "Order Date",
"fieldId": null,
"dataType": "date",
"position": 3
},
"RequiredDate": {
"name": "RequiredDate",
"label": "Required Date",
"fieldId": null,
"dataType": "date",
"position": 4
},
"ShippedDate": {
"name": "ShippedDate",
"label": "Shipped Date",
"fieldId": null,
"dataType": "date",
"position": 5
},
"ShipVia": {
"name": "ShipVia",
"label": "Ship Via",
"fieldId": null,
"dataType": "double",
"position": 6
},
"Freight": {
"name": "Freight",
"label": "Freight",
"fieldId": null,
"dataType": "double",
"position": 7
},
"ShipName": {
"name": "ShipName",
"label": "Ship Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 8
},
"ShipAddress": {
"name": "ShipAddress",
"label": "Ship Address",
"fieldId": null,
"dataType": "keyword_text",
"position": 9
},
"ShipCity": {
"name": "ShipCity",
"label": "Ship City",
"fieldId": null,
"dataType": "keyword_text",
"position": 10
},
"ShipRegion": {
"name": "ShipRegion",
"label": "Ship Region",
"fieldId": null,
"dataType": "keyword_text",
"position": 11
},
"ShipPostalCode": {
"name": "ShipPostalCode",
"label": "Ship Postal Code",
"fieldId": null,
"dataType": "keyword_text",
"position": 12
},
"ShipCountry": {
"name": "ShipCountry",
"label": "Ship Country",
"fieldId": null,
"dataType": "keyword_text",
"position": 13
},
"ProductID": {
"name": "ProductID",
"label": "Product",
"fieldId": null,
"dataType": "double",
"position": 14
},
"ProductName": {
"name": "ProductName",
"label": "Product Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 15
},
"SupplierID": {
"name": "SupplierID",
"label": "Supplier",
"fieldId": null,
"dataType": "double",
"position": 16
},
"CategoryID": {
"name": "CategoryID",
"label": "Category",
"fieldId": null,
"dataType": "double",
"position": 17
},
"QuantityPerUnit": {
"name": "QuantityPerUnit",
"label": "Quantity Per Unit",
"fieldId": null,
"dataType": "keyword_text",
"position": 18
},
"UnitPrice": {
"name": "UnitPrice",
"label": "Unit Price",
"fieldId": null,
"dataType": "double",
"position": 19
},
"UnitsInStock": {
"name": "UnitsInStock",
"label": "Units In Stock",
"fieldId": null,
"dataType": "double",
"position": 20
},
"UnitsOnOrder": {
"name": "UnitsOnOrder",
"label": "Units On Order",
"fieldId": null,
"dataType": "double",
"position": 21
},
"ReorderLevel": {
"name": "ReorderLevel",
"label": "Reorder Level",
"fieldId": null,
"dataType": "double",
"position": 22
},
"Discontinued": {
"name": "Discontinued",
"label": "Discontinued",
"fieldId": null,
"dataType": "double",
"position": 23
},
"CompanyName": {
"name": "CompanyName",
"label": "Company Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 25
},
"ContactName": {
"name": "ContactName",
"label": "Contact Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 26
},
"ContactTitle": {
"name": "ContactTitle",
"label": "Contact Title",
"fieldId": null,
"dataType": "keyword_text",
"position": 27
},
"Address": {
"name": "Address",
"label": "Address",
"fieldId": null,
"dataType": "keyword_text",
"position": 28
},
"City": {
"name": "City",
"label": "City",
"fieldId": null,
"dataType": "keyword_text",
"position": 29
},
"Region": {
"name": "Region",
"label": "Region",
"fieldId": null,
"dataType": "keyword_text",
"position": 30
},
"PostalCode": {
"name": "PostalCode",
"label": "Postal Code",
"fieldId": null,
"dataType": "keyword_text",
"position": 31
},
"Country": {
"name": "Country",
"label": "Country",
"fieldId": null,
"dataType": "keyword_text",
"position": 32
},
"Phone": {
"name": "Phone",
"label": "Phone",
"fieldId": null,
"dataType": "keyword_text",
"position": 33
},
"Fax": {
"name": "Fax",
"label": "Fax",
"fieldId": null,
"dataType": "keyword_text",
"position": 34
}
},
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": true,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"ownerId": "admin",
"slug": "orders-by-region-draft",
"name": "Orders by Region (Draft)",
"description": null,
"shared": false,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {
"grid": {
"groups": [],
"sortBy": [],
"columns": {
"Fax": {
"position": 33
},
"City": {
"position": 28
},
"Phone": {
"position": 32
},
"Region": {
"position": 29
},
"Address": {
"position": 27
},
"Country": {
"position": 31
},
"Freight": {
"format": {
"width": {
"num": 100,
"type": "px"
}
},
"position": 7
},
"OrderID": {
"format": {
"width": {
"num": 95,
"type": "px"
}
},
"position": 0
},
"ShipVia": {
"format": {
"width": {
"num": 107,
"type": "px"
}
},
"position": 6
},
"ShipCity": {
"format": {
"width": {
"num": 120,
"type": "px"
}
},
"position": 10
},
"ShipName": {
"format": {
"width": {
"num": 207,
"type": "px"
}
},
"position": 8
},
"OrderDate": {
"format": {
"width": {
"num": 122,
"type": "px"
}
},
"position": 3
},
"ProductID": {
"position": 14
},
"UnitPrice": {
"position": 19
},
"CategoryID": {
"position": 17
},
"CustomerID": {
"format": {
"width": {
"num": 117,
"type": "px"
}
},
"position": 1
},
"EmployeeID": {
"format": {
"width": {
"num": 117,
"type": "px"
}
},
"position": 2
},
"PostalCode": {
"position": 30
},
"ShipRegion": {
"format": {
"width": {
"num": 129,
"type": "px"
}
},
"position": 11
},
"SupplierID": {
"position": 16
},
"CompanyName": {
"position": 24
},
"ContactName": {
"position": 25
},
"ProductName": {
"position": 15
},
"ShipAddress": {
"format": {
"width": {
"num": 283,
"type": "px"
}
},
"position": 9
},
"ShipCountry": {
"position": 13
},
"ShippedDate": {
"format": {
"width": {
"num": 137,
"type": "px"
}
},
"position": 5
},
"ContactTitle": {
"position": 26
},
"Discontinued": {
"position": 23
},
"ReorderLevel": {
"position": 22
},
"RequiredDate": {
"format": {
"width": {
"num": 141,
"type": "px"
}
},
"position": 4
},
"UnitsInStock": {
"position": 20
},
"UnitsOnOrder": {
"position": 21
},
"ShipPostalCode": {
"format": {
"width": {
"num": 159,
"type": "px"
}
},
"position": 12
},
"QuantityPerUnit": {
"position": 18
}
},
"pageSize": 25,
"usePaging": false,
"aggregates": [],
"summaryOnly": false,
"showSubheaders": false,
"displayHiddenFields": true,
"showOverallAggregates": true
},
"chips": [],
"filter": {},
"useFakeData": false
},
"inputs": {
"multiInput": {
"inputs": [],
"instructions": ""
}
},
"language": "sql",
"flow": [],
"payload": "SELECT o.*, p.*, c.*\nFROM orders o\nLEFT JOIN order_details od on o.\"OrderID\" = od.\"OrderID\"\nLEFT JOIN customers c on c.\"CustomerID\" = o.\"CustomerID\"\nLEFT JOIN products p on p.\"ProductID\" = od.\"ProductID\"",
"defnUpdatedAt": "2026-01-15T16:20:00.000Z",
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": "00000000-0000-4000-8000-000000000003",
"editingId": "00000000-0000-4000-8000-000000000001",
"folderId": null,
"datasource": {
"defaultLinkType": "sql",
"aiSystemMessage": "This is a PostgresSQL database. Identifiers are case-sensitive by default. \n Always surround all column names, table names, and schema names in double-quotes (\"). \n For example:\n SELECT \"OrderID\", \"ShipCountry\" FROM \"public\".\"orders\" WHERE \"ShipCity\" = 'Raleigh';\n ---",
"family": "sql",
"languages": [
"informer",
"sql",
"distinctValue",
"… 2 more items (5 total) — omitted from docs"
],
"naturalId": "admin:northwind",
"image": "/opt/informer/packages/informer-server/modules/sql/images/postgres.svg",
"compatibility": [],
"permissions": {
"assignTags": true,
"edit": true,
"delete": true,
"share": true,
"write": true,
"changeOwner": true,
"ping": true,
"scan": true,
"downloadSchema": true,
"importData": true,
"importSchema": true,
"rename": true,
"editConnection": true,
"createLink": true,
"setWrite": true,
"createSuite": true,
"createFieldExpression": true,
"createMapping": false,
"bundle": true,
"query": true
},
"id": "00000000-0000-4000-8000-000000000003",
"tenant": "acme",
"ownerId": "admin",
"slug": "northwind",
"name": "Northwind",
"description": null,
"embedded": false,
"type": "postgres",
"connection": {
"host": "localhost",
"pool": {
"max": 5,
"min": 0,
"idle": 10000,
"acquire": 10000
},
"port": 5432,
"user": "northwinduser",
"database": "northwind",
"password": "encrypted:iv:0000000000000000",
"idleTimeoutMillis": 7
},
"scannedAt": "2026-01-15T16:20:00.000Z",
"schemaUpdatedAt": "2026-01-15T16:20:00.000Z",
"rescanRequired": false,
"shared": false,
"schemas": [
"public"
],
"source": null,
"sourceId": null,
"settings": {
"multiSchema": false,
"useFakeData": false,
"remoteQueryBatchSize": {
"multiKey": 500,
"singleKey": 500
},
"usePreparedStatements": false
},
"data": null,
"appId": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"folderId": null,
"fileId": null,
"shares": []
},
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/sql"
}
},
"id": "sql",
"name": "drivers:query_language.sql.name",
"description": "drivers:query_language.sql.description",
"image": "/images/query/native-sql-query.svg",
"color": "deepPurple",
"preProcessors": [
"iqlFieldIdProcessor",
null
],
"formatInputParams": null
}
}
}
Single draft per user
Each user can have only one draft per Query. Calling this endpoint again as the same user returns the same draft instance.
GET /api/queries/{id}/draft
Get the caller's draft for a Query.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | UUID or ownerId:slug natural id of the original Query |
Response:
Returns the caller's existing draft with 200, a Location header to the
draft's own lookup, an inf:original HAL link back to the Query being edited, an
inf:commit-draft link, and an embedded inf:datasource. The response also
carries a computed hasUserSettings boolean (true when any user has a
non-empty custom view for the original). When no draft exists for the caller, the
route answers 404.
Get the draftGET /api/queries/00000000-0000-4000-8000-000000000001/draft
GET /api/queries/{id}/draft returns the caller's existing draft for the given (original) query id. Responds 200 with a Location header to the draft, an `inf:original` HAL link back to the query being edited, an `inf:commit-draft` link, and an embedded `inf:datasource`. The response also carries a computed `hasUserSettings` boolean (true when any user has a non-empty custom view for the original). 404s when no draft exists.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/_export"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-region-draft/input-templates{?dataType,wildcard}",
"templated": true
},
"inf:original": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001"
},
"inf:commit-draft": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit"
}
},
"naturalId": "admin:orders-by-region-draft",
"fields": {
"OrderID": {
"name": "OrderID",
"label": "Order",
"fieldId": null,
"dataType": "double",
"position": 0
},
"CustomerID": {
"name": "CustomerID",
"label": "Customer",
"fieldId": null,
"dataType": "keyword_text",
"position": 1
},
"EmployeeID": {
"name": "EmployeeID",
"label": "Employee",
"fieldId": null,
"dataType": "double",
"position": 2
},
"OrderDate": {
"name": "OrderDate",
"label": "Order Date",
"fieldId": null,
"dataType": "date",
"position": 3
},
"RequiredDate": {
"name": "RequiredDate",
"label": "Required Date",
"fieldId": null,
"dataType": "date",
"position": 4
},
"ShippedDate": {
"name": "ShippedDate",
"label": "Shipped Date",
"fieldId": null,
"dataType": "date",
"position": 5
},
"ShipVia": {
"name": "ShipVia",
"label": "Ship Via",
"fieldId": null,
"dataType": "double",
"position": 6
},
"Freight": {
"name": "Freight",
"label": "Freight",
"fieldId": null,
"dataType": "double",
"position": 7
},
"ShipName": {
"name": "ShipName",
"label": "Ship Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 8
},
"ShipAddress": {
"name": "ShipAddress",
"label": "Ship Address",
"fieldId": null,
"dataType": "keyword_text",
"position": 9
},
"ShipCity": {
"name": "ShipCity",
"label": "Ship City",
"fieldId": null,
"dataType": "keyword_text",
"position": 10
},
"ShipRegion": {
"name": "ShipRegion",
"label": "Ship Region",
"fieldId": null,
"dataType": "keyword_text",
"position": 11
},
"ShipPostalCode": {
"name": "ShipPostalCode",
"label": "Ship Postal Code",
"fieldId": null,
"dataType": "keyword_text",
"position": 12
},
"ShipCountry": {
"name": "ShipCountry",
"label": "Ship Country",
"fieldId": null,
"dataType": "keyword_text",
"position": 13
},
"ProductID": {
"name": "ProductID",
"label": "Product",
"fieldId": null,
"dataType": "double",
"position": 14
},
"ProductName": {
"name": "ProductName",
"label": "Product Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 15
},
"SupplierID": {
"name": "SupplierID",
"label": "Supplier",
"fieldId": null,
"dataType": "double",
"position": 16
},
"CategoryID": {
"name": "CategoryID",
"label": "Category",
"fieldId": null,
"dataType": "double",
"position": 17
},
"QuantityPerUnit": {
"name": "QuantityPerUnit",
"label": "Quantity Per Unit",
"fieldId": null,
"dataType": "keyword_text",
"position": 18
},
"UnitPrice": {
"name": "UnitPrice",
"label": "Unit Price",
"fieldId": null,
"dataType": "double",
"position": 19
},
"UnitsInStock": {
"name": "UnitsInStock",
"label": "Units In Stock",
"fieldId": null,
"dataType": "double",
"position": 20
},
"UnitsOnOrder": {
"name": "UnitsOnOrder",
"label": "Units On Order",
"fieldId": null,
"dataType": "double",
"position": 21
},
"ReorderLevel": {
"name": "ReorderLevel",
"label": "Reorder Level",
"fieldId": null,
"dataType": "double",
"position": 22
},
"Discontinued": {
"name": "Discontinued",
"label": "Discontinued",
"fieldId": null,
"dataType": "double",
"position": 23
},
"CompanyName": {
"name": "CompanyName",
"label": "Company Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 25
},
"ContactName": {
"name": "ContactName",
"label": "Contact Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 26
},
"ContactTitle": {
"name": "ContactTitle",
"label": "Contact Title",
"fieldId": null,
"dataType": "keyword_text",
"position": 27
},
"Address": {
"name": "Address",
"label": "Address",
"fieldId": null,
"dataType": "keyword_text",
"position": 28
},
"City": {
"name": "City",
"label": "City",
"fieldId": null,
"dataType": "keyword_text",
"position": 29
},
"Region": {
"name": "Region",
"label": "Region",
"fieldId": null,
"dataType": "keyword_text",
"position": 30
},
"PostalCode": {
"name": "PostalCode",
"label": "Postal Code",
"fieldId": null,
"dataType": "keyword_text",
"position": 31
},
"Country": {
"name": "Country",
"label": "Country",
"fieldId": null,
"dataType": "keyword_text",
"position": 32
},
"Phone": {
"name": "Phone",
"label": "Phone",
"fieldId": null,
"dataType": "keyword_text",
"position": 33
},
"Fax": {
"name": "Fax",
"label": "Fax",
"fieldId": null,
"dataType": "keyword_text",
"position": 34
}
},
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": true,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"ownerId": "admin",
"slug": "orders-by-region-draft",
"name": "Orders by Region (Draft)",
"description": null,
"shared": false,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {
"grid": {
"groups": [],
"sortBy": [],
"columns": {
"Fax": {
"position": 33
},
"City": {
"position": 28
},
"Phone": {
"position": 32
},
"Region": {
"position": 29
},
"Address": {
"position": 27
},
"Country": {
"position": 31
},
"Freight": {
"format": {
"width": {
"num": 100,
"type": "px"
}
},
"position": 7
},
"OrderID": {
"format": {
"width": {
"num": 95,
"type": "px"
}
},
"position": 0
},
"ShipVia": {
"format": {
"width": {
"num": 107,
"type": "px"
}
},
"position": 6
},
"ShipCity": {
"format": {
"width": {
"num": 120,
"type": "px"
}
},
"position": 10
},
"ShipName": {
"format": {
"width": {
"num": 207,
"type": "px"
}
},
"position": 8
},
"OrderDate": {
"format": {
"width": {
"num": 122,
"type": "px"
}
},
"position": 3
},
"ProductID": {
"position": 14
},
"UnitPrice": {
"position": 19
},
"CategoryID": {
"position": 17
},
"CustomerID": {
"format": {
"width": {
"num": 117,
"type": "px"
}
},
"position": 1
},
"EmployeeID": {
"format": {
"width": {
"num": 117,
"type": "px"
}
},
"position": 2
},
"PostalCode": {
"position": 30
},
"ShipRegion": {
"format": {
"width": {
"num": 129,
"type": "px"
}
},
"position": 11
},
"SupplierID": {
"position": 16
},
"CompanyName": {
"position": 24
},
"ContactName": {
"position": 25
},
"ProductName": {
"position": 15
},
"ShipAddress": {
"format": {
"width": {
"num": 283,
"type": "px"
}
},
"position": 9
},
"ShipCountry": {
"position": 13
},
"ShippedDate": {
"format": {
"width": {
"num": 137,
"type": "px"
}
},
"position": 5
},
"ContactTitle": {
"position": 26
},
"Discontinued": {
"position": 23
},
"ReorderLevel": {
"position": 22
},
"RequiredDate": {
"format": {
"width": {
"num": 141,
"type": "px"
}
},
"position": 4
},
"UnitsInStock": {
"position": 20
},
"UnitsOnOrder": {
"position": 21
},
"ShipPostalCode": {
"format": {
"width": {
"num": 159,
"type": "px"
}
},
"position": 12
},
"QuantityPerUnit": {
"position": 18
}
},
"pageSize": 25,
"usePaging": false,
"aggregates": [],
"summaryOnly": false,
"showSubheaders": false,
"displayHiddenFields": true,
"showOverallAggregates": true
},
"chips": [],
"filter": {},
"useFakeData": false
},
"inputs": {
"multiInput": {
"inputs": [],
"instructions": ""
}
},
"language": "sql",
"flow": [],
"payload": "SELECT o.*, p.*, c.*\nFROM orders o\nLEFT JOIN order_details od on o.\"OrderID\" = od.\"OrderID\"\nLEFT JOIN customers c on c.\"CustomerID\" = o.\"CustomerID\"\nLEFT JOIN products p on p.\"ProductID\" = od.\"ProductID\"",
"defnUpdatedAt": "2026-01-15T16:20:00.000Z",
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": "00000000-0000-4000-8000-000000000003",
"editingId": "00000000-0000-4000-8000-000000000001",
"folderId": null,
"hasUserSettings": false,
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/sql"
}
},
"id": "sql",
"name": "drivers:query_language.sql.name",
"description": "drivers:query_language.sql.description",
"image": "/images/query/native-sql-query.svg",
"color": "deepPurple",
"preProcessors": [
"iqlFieldIdProcessor",
null
],
"formatInputParams": null
},
"inf:datasource": {
"_links": {
"self": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003"
},
"inf:features": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/features"
},
"inf:comments": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/comments"
},
"inf:links": {
"href": "https://informer.example.com/api/datasources/admin%3Anorthwind/links{?sort,limit,start,q,show,expand}",
"templated": true
},
"inf:link-types": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/link-types"
},
"inf:favorite": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/favorite"
},
"inf:settings-components": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/settings-components"
},
"inf:column-types": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/column-types"
},
"inf:mappings": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/mappings{?sort,limit,start,q,show,set,expand}",
"templated": true
},
"inf:scan": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/_scan"
},
"inf:ping": {
"href": "https://informer.example.com/api/datasources/00000000-0000-4000-8000-000000000003/_ping"
},
"inf:query": {
"href": "https://informer.example.com/api/datasources/admin%3Anorthwind/_query{?limit,output,cache,fakeData,unmappedFields,disableCriteria,clearCache,applyFormatting}",
"templated": true
},
"inf:query-string": {
"href": "https://informer.example.com/api/datasources/admin%3Anorthwind/_query-string"
},
"inf:suites": {
"href": "https://informer.example.com/api/datasources/admin%3Anorthwind/suites{?mapping}",
"templated": true
}
},
"defaultLinkType": "sql",
"aiSystemMessage": "This is a PostgresSQL database. Identifiers are case-sensitive by default. \n Always surround all column names, table names, and schema names in double-quotes (\"). \n For example:\n SELECT \"OrderID\", \"ShipCountry\" FROM \"public\".\"orders\" WHERE \"ShipCity\" = 'Raleigh';\n ---",
"family": "sql",
"languages": [
"informer",
"sql",
"distinctValue",
"… 2 more items (5 total) — omitted from docs"
],
"naturalId": "admin:northwind",
"image": "/opt/informer/packages/informer-server/modules/sql/images/postgres.svg",
"compatibility": [],
"permissions": {
"assignTags": true,
"edit": true,
"delete": true,
"share": true,
"write": true,
"changeOwner": true,
"ping": true,
"scan": true,
"downloadSchema": true,
"importData": true,
"importSchema": true,
"rename": true,
"editConnection": true,
"createLink": true,
"setWrite": true,
"createSuite": true,
"createFieldExpression": true,
"createMapping": false,
"bundle": true,
"query": true
},
"id": "00000000-0000-4000-8000-000000000003",
"tenant": "acme",
"ownerId": "admin",
"slug": "northwind",
"name": "Northwind",
"description": null,
"embedded": false,
"type": "postgres",
"connection": {
"host": "localhost",
"pool": {
"max": 5,
"min": 0,
"idle": 10000,
"acquire": 10000
},
"port": 5432,
"user": "northwinduser",
"database": "northwind",
"password": "encrypted:iv:0000000000000000",
"idleTimeoutMillis": 7
},
"scannedAt": "2026-01-15T16:20:00.000Z",
"schemaUpdatedAt": "2026-01-15T16:20:00.000Z",
"rescanRequired": false,
"shared": false,
"schemas": [
"public"
],
"source": null,
"sourceId": null,
"settings": {
"multiSchema": false,
"useFakeData": false,
"remoteQueryBatchSize": {
"multiKey": 500,
"singleKey": 500
},
"usePreparedStatements": false
},
"appId": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"folderId": null,
"fileId": null,
"shares": [],
"_embedded": {
"inf:driver": {
"_links": {
"self": {
"href": "https://informer.example.com/api/datasource-drivers/postgres"
},
"edit": {
"href": "https://informer.example.com/api/datasource-drivers/postgres/connection-form"
},
"image": {
"href": "https://informer.example.com/api/datasource-drivers/postgres/image"
},
"inf:ping": {
"href": "https://informer.example.com/api/datasource-drivers/postgres/_ping"
},
"inf:scan": {
"href": "https://informer.example.com/_scan"
}
},
"id": "postgres",
"queryDialect": "pg",
"name": "PostgreSQL",
"color": "blue",
"maxQueryParameters": 50000,
"languages": [
"informer",
"sql",
"distinctValue",
"… 2 more items (5 total) — omitted from docs"
],
"allowOnlyUpdateExisting": true,
"aiSystemMessage": "This is a PostgresSQL database. Identifiers are case-sensitive by default. \n Always surround all column names, table names, and schema names in double-quotes (\"). \n For example:\n SELECT \"OrderID\", \"ShipCountry\" FROM \"public\".\"orders\" WHERE \"ShipCity\" = 'Raleigh';\n ---",
"support": {
"queryDesigner": {
"iql": {
"supportsIgnoreCaseStringComparison": true,
"aggregatePayloadFields": true,
"countStarPayloadField": true,
"nativeOrdering": true,
"distinctValues": true
}
}
},
"create": true,
"allowFullScan": true,
"hasMappings": true,
"family": "sql",
"image": "/opt/informer/packages/informer-server/modules/sql/images/postgres.svg",
"defaultLinkType": "sql"
}
}
}
}
}
| Property | Description |
|---|---|
editingId | Id of the original Query being edited |
ownerId | User id of the draft owner (a user, never a team) |
name | Original name with the " (Draft)" suffix |
hasUserSettings | Whether any user has a non-empty custom view for the original |
PUT /api/queries/{id}/draft
Create the draft if absent, or update it with the supplied changes.
Authentication: Required
Permission: permission.query.write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | UUID or ownerId:slug natural id of the original Query |
Request Body:
The payload is stripUnknown, so unrecognized fields are dropped rather than
rejected.
| Field | Type | Required | Description |
|---|---|---|---|
language | string | No | Query language |
payload | object | No | Language-specific query definition |
inputs | object | No | Input parameter definitions |
flow | array | No | Transformation steps |
datasourceId | string | No | Datasource id |
settings | object | No | Query settings |
fields | object | No | Field metadata (default {}) |
Example Request:
{
"inputs": {
"region": {
"type": "string",
"label": "Sales Region",
"default": "West"
}
},
"settings": { "timeout": 90000 }
}
Response:
Runs in a transaction and responds 200 with the draft and a Location header
to the draft.
Update the draftPUT /api/queries/00000000-0000-4000-8000-000000000001/draft
PUT /api/queries/{id}/draft creates the draft if absent or updates it with the supplied changes, in a transaction. Payload is stripUnknown and limited to { language?, payload?, inputs?, flow?, datasourceId?, settings?, fields? } (`fields` defaults to {}). Returns 200 with a Location header to the draft. Note: provided fields whole-value replace the corresponding draft columns; `settings` is NOT deep-merged.
Request body
{
"inputs": {
"region": {
"type": "string",
"label": "Sales Region",
"default": "West"
}
},
"settings": {
"timeout": 90000
}
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-customer-draft/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-customer-draft/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-customer-draft/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-customer-draft/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-customer-draft/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/_export"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-customer-draft/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-customer-draft/input-templates{?dataType,wildcard}",
"templated": true
}
},
"naturalId": "admin:orders-by-customer-draft",
"fields": {},
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": true,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"ownerId": "admin",
"slug": "orders-by-customer-draft",
"name": "Orders by Customer (Draft)",
"description": null,
"shared": false,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {
"timeout": 90000
},
"inputs": {
"region": {
"type": "string",
"label": "Sales Region",
"default": "West"
}
},
"language": "sql",
"flow": [],
"payload": "SELECT o.*, p.*, c.*\nFROM orders o\nLEFT JOIN order_details od on o.\"OrderID\" = od.\"OrderID\"\nLEFT JOIN customers c on c.\"CustomerID\" = o.\"CustomerID\"\nLEFT JOIN products p on p.\"ProductID\" = od.\"ProductID\"",
"defnUpdatedAt": "2026-01-15T16:20:00.000Z",
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": "00000000-0000-4000-8000-000000000003",
"editingId": "00000000-0000-4000-8000-000000000001",
"folderId": null,
"datasource": {
"defaultLinkType": "sql",
"aiSystemMessage": "This is a PostgresSQL database. Identifiers are case-sensitive by default. \n Always surround all column names, table names, and schema names in double-quotes (\"). \n For example:\n SELECT \"OrderID\", \"ShipCountry\" FROM \"public\".\"orders\" WHERE \"ShipCity\" = 'Raleigh';\n ---",
"family": "sql",
"languages": [
"informer",
"sql",
"distinctValue",
"… 2 more items (5 total) — omitted from docs"
],
"naturalId": "admin:northwind",
"image": "/opt/informer/packages/informer-server/modules/sql/images/postgres.svg",
"compatibility": [],
"permissions": {
"assignTags": true,
"edit": true,
"delete": true,
"share": true,
"write": true,
"changeOwner": true,
"ping": true,
"scan": true,
"downloadSchema": true,
"importData": true,
"importSchema": true,
"rename": true,
"editConnection": true,
"createLink": true,
"setWrite": true,
"createSuite": true,
"createFieldExpression": true,
"createMapping": false,
"bundle": true,
"query": true
},
"id": "00000000-0000-4000-8000-000000000003",
"tenant": "acme",
"ownerId": "admin",
"slug": "northwind",
"name": "Northwind",
"description": null,
"embedded": false,
"type": "postgres",
"connection": {
"host": "localhost",
"pool": {
"max": 5,
"min": 0,
"idle": 10000,
"acquire": 10000
},
"port": 5432,
"user": "northwinduser",
"database": "northwind",
"password": "encrypted:iv:0000000000000000",
"idleTimeoutMillis": 7
},
"scannedAt": "2026-01-15T16:20:00.000Z",
"schemaUpdatedAt": "2026-01-15T16:20:00.000Z",
"rescanRequired": false,
"shared": false,
"schemas": [
"public"
],
"source": null,
"sourceId": null,
"settings": {
"multiSchema": false,
"useFakeData": false,
"remoteQueryBatchSize": {
"multiKey": 500,
"singleKey": 500
},
"usePreparedStatements": false
},
"data": null,
"appId": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"folderId": null,
"fileId": null,
"shares": []
},
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/sql"
}
},
"id": "sql",
"name": "drivers:query_language.sql.name",
"description": "drivers:query_language.sql.description",
"image": "/images/query/native-sql-query.svg",
"color": "deepPurple",
"preProcessors": [
"iqlFieldIdProcessor",
null
],
"formatInputParams": null
}
}
}
Provided values replace, they do not merge
Each provided field is a whole-value replace of the corresponding draft column.
In particular settings is not deep-merged: sending settings overwrites
the draft's entire settings object. Include every key you want to keep.
Testing changes
After updating a draft, run the draft through the execution routes to test the Query without committing the changes back onto the original.
DELETE /api/queries/{id}/draft
Discard the caller's draft for a Query, leaving the original unchanged.
Authentication: Required
Permission: permission.query.write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | UUID or ownerId:slug natural id of the original Query |
Response:
Removes the draft through the read_access scope and responds 200 with an
empty body (the Informer convention), not 204. A missing draft answers
404. The original Query is untouched.
Discard the draftDELETE /api/queries/00000000-0000-4000-8000-000000000001/draft
DELETE /api/queries/{id}/draft discards the caller's draft (db.remove on the read_access scope), leaving the original query unchanged. Requires permission.query.write. Returns 200 with an EMPTY body (Informer convention), NOT 204 as commonly assumed; a missing draft 404s.
Response · 200 · no body
POST /api/queries/{id}/draft/_commit
Commit a draft back onto the original Query.
Authentication: Required
Permission: permission.query.write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | UUID or ownerId:slug natural id of the original Query |
Request Body:
The payload is stripUnknown and the whole body defaults to {}.
| Field | Type | Default | Description |
|---|---|---|---|
clearAllUserSettings | boolean | true | Whether to clear all user settings and cached data when committing |
Example Request:
{
"clearAllUserSettings": true
}
Response:
Copies the editable fields onto the original (stamping a fresh defnUpdatedAt),
deletes the draft for non-embedded queries, logs a queryUpdated activity, and
responds 200 with the updated live Query (note editingId is null and
the name has no " (Draft)" suffix). The whole operation runs in one transaction.
Commit the draftPOST /api/queries/00000000-0000-4000-8000-000000000001/draft/_commit
POST /api/queries/{id}/draft/_commit applies the draft back onto the original query and (for non-embedded queries) deletes the draft, all in one transaction. Requires permission.query.write. Copies the editable fields onto the original (stamping a fresh defnUpdatedAt). When clearAllUserSettings is true (the default), it also clears every user's UserSettings plus the embedded datasets' DatasetFields, indexed data, dataUpdatedAt, and JobDataset settings. Logs a `queryUpdated` activity and returns the updated LIVE query (200). Payload { clearAllUserSettings?: boolean = true } is stripUnknown and the whole body defaults to {}.
Request body
{
"clearAllUserSettings": true
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit"
},
"inf:run": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-ship-date/_run{?progress}",
"templated": true
},
"inf:benchmark": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-ship-date/_benchmark{?progress}",
"templated": true
},
"inf:execute": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-ship-date/_execute{?output,limit,pretty,timezone,applyFormatting}",
"templated": true
},
"inf:comments": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit/comments"
},
"inf:dataset": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-ship-date/dataset"
},
"inf:query-shares": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit/shares"
},
"inf:query-share": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit/shares/{principalId}",
"templated": true
},
"inf:draft": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-ship-date/draft"
},
"inf:query-tags": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit/tags"
},
"inf:favorite": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit/favorite"
},
"inf:query-tag": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit/tags/{tagId}",
"templated": true
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit/_export"
},
"edit": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-ship-date/_edit"
},
"inf:owner": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/draft/_commit/owner"
},
"inf:user-settings": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-ship-date/settings"
},
"inf:input-templates": {
"href": "https://informer.example.com/api/queries/admin%3Aorders-by-ship-date/input-templates{?dataType,wildcard}",
"templated": true
}
},
"naturalId": "admin:orders-by-ship-date",
"fields": {
"OrderID": {
"name": "OrderID",
"label": "Order",
"fieldId": null,
"dataType": "double",
"position": 0
},
"CustomerID": {
"name": "CustomerID",
"label": "Customer",
"fieldId": null,
"dataType": "keyword_text",
"position": 1
},
"EmployeeID": {
"name": "EmployeeID",
"label": "Employee",
"fieldId": null,
"dataType": "double",
"position": 2
},
"OrderDate": {
"name": "OrderDate",
"label": "Order Date",
"fieldId": null,
"dataType": "date",
"position": 3
},
"RequiredDate": {
"name": "RequiredDate",
"label": "Required Date",
"fieldId": null,
"dataType": "date",
"position": 4
},
"ShippedDate": {
"name": "ShippedDate",
"label": "Shipped Date",
"fieldId": null,
"dataType": "date",
"position": 5
},
"ShipVia": {
"name": "ShipVia",
"label": "Ship Via",
"fieldId": null,
"dataType": "double",
"position": 6
},
"Freight": {
"name": "Freight",
"label": "Freight",
"fieldId": null,
"dataType": "double",
"position": 7
},
"ShipName": {
"name": "ShipName",
"label": "Ship Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 8
},
"ShipAddress": {
"name": "ShipAddress",
"label": "Ship Address",
"fieldId": null,
"dataType": "keyword_text",
"position": 9
},
"ShipCity": {
"name": "ShipCity",
"label": "Ship City",
"fieldId": null,
"dataType": "keyword_text",
"position": 10
},
"ShipRegion": {
"name": "ShipRegion",
"label": "Ship Region",
"fieldId": null,
"dataType": "keyword_text",
"position": 11
},
"ShipPostalCode": {
"name": "ShipPostalCode",
"label": "Ship Postal Code",
"fieldId": null,
"dataType": "keyword_text",
"position": 12
},
"ShipCountry": {
"name": "ShipCountry",
"label": "Ship Country",
"fieldId": null,
"dataType": "keyword_text",
"position": 13
},
"ProductID": {
"name": "ProductID",
"label": "Product",
"fieldId": null,
"dataType": "double",
"position": 14
},
"ProductName": {
"name": "ProductName",
"label": "Product Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 15
},
"SupplierID": {
"name": "SupplierID",
"label": "Supplier",
"fieldId": null,
"dataType": "double",
"position": 16
},
"CategoryID": {
"name": "CategoryID",
"label": "Category",
"fieldId": null,
"dataType": "double",
"position": 17
},
"QuantityPerUnit": {
"name": "QuantityPerUnit",
"label": "Quantity Per Unit",
"fieldId": null,
"dataType": "keyword_text",
"position": 18
},
"UnitPrice": {
"name": "UnitPrice",
"label": "Unit Price",
"fieldId": null,
"dataType": "double",
"position": 19
},
"UnitsInStock": {
"name": "UnitsInStock",
"label": "Units In Stock",
"fieldId": null,
"dataType": "double",
"position": 20
},
"UnitsOnOrder": {
"name": "UnitsOnOrder",
"label": "Units On Order",
"fieldId": null,
"dataType": "double",
"position": 21
},
"ReorderLevel": {
"name": "ReorderLevel",
"label": "Reorder Level",
"fieldId": null,
"dataType": "double",
"position": 22
},
"Discontinued": {
"name": "Discontinued",
"label": "Discontinued",
"fieldId": null,
"dataType": "double",
"position": 23
},
"CompanyName": {
"name": "CompanyName",
"label": "Company Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 25
},
"ContactName": {
"name": "ContactName",
"label": "Contact Name",
"fieldId": null,
"dataType": "keyword_text",
"position": 26
},
"ContactTitle": {
"name": "ContactTitle",
"label": "Contact Title",
"fieldId": null,
"dataType": "keyword_text",
"position": 27
},
"Address": {
"name": "Address",
"label": "Address",
"fieldId": null,
"dataType": "keyword_text",
"position": 28
},
"City": {
"name": "City",
"label": "City",
"fieldId": null,
"dataType": "keyword_text",
"position": 29
},
"Region": {
"name": "Region",
"label": "Region",
"fieldId": null,
"dataType": "keyword_text",
"position": 30
},
"PostalCode": {
"name": "PostalCode",
"label": "Postal Code",
"fieldId": null,
"dataType": "keyword_text",
"position": 31
},
"Country": {
"name": "Country",
"label": "Country",
"fieldId": null,
"dataType": "keyword_text",
"position": 32
},
"Phone": {
"name": "Phone",
"label": "Phone",
"fieldId": null,
"dataType": "keyword_text",
"position": 33
},
"Fax": {
"name": "Fax",
"label": "Fax",
"fieldId": null,
"dataType": "keyword_text",
"position": 34
}
},
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": true,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000001",
"tenant": "acme",
"ownerId": "admin",
"slug": "orders-by-ship-date",
"name": "Orders by Ship Date",
"description": null,
"shared": false,
"embedded": false,
"source": null,
"sourceId": null,
"settings": {
"grid": {
"groups": [],
"sortBy": [],
"columns": {
"Fax": {
"position": 33
},
"City": {
"position": 28
},
"Phone": {
"position": 32
},
"Region": {
"position": 29
},
"Address": {
"position": 27
},
"Country": {
"position": 31
},
"Freight": {
"format": {
"width": {
"num": 100,
"type": "px"
}
},
"position": 7
},
"OrderID": {
"format": {
"width": {
"num": 95,
"type": "px"
}
},
"position": 0
},
"ShipVia": {
"format": {
"width": {
"num": 107,
"type": "px"
}
},
"position": 6
},
"ShipCity": {
"format": {
"width": {
"num": 120,
"type": "px"
}
},
"position": 10
},
"ShipName": {
"format": {
"width": {
"num": 207,
"type": "px"
}
},
"position": 8
},
"OrderDate": {
"format": {
"width": {
"num": 122,
"type": "px"
}
},
"position": 3
},
"ProductID": {
"position": 14
},
"UnitPrice": {
"position": 19
},
"CategoryID": {
"position": 17
},
"CustomerID": {
"format": {
"width": {
"num": 117,
"type": "px"
}
},
"position": 1
},
"EmployeeID": {
"format": {
"width": {
"num": 117,
"type": "px"
}
},
"position": 2
},
"PostalCode": {
"position": 30
},
"ShipRegion": {
"format": {
"width": {
"num": 129,
"type": "px"
}
},
"position": 11
},
"SupplierID": {
"position": 16
},
"CompanyName": {
"position": 24
},
"ContactName": {
"position": 25
},
"ProductName": {
"position": 15
},
"ShipAddress": {
"format": {
"width": {
"num": 283,
"type": "px"
}
},
"position": 9
},
"ShipCountry": {
"position": 13
},
"ShippedDate": {
"format": {
"width": {
"num": 137,
"type": "px"
}
},
"position": 5
},
"ContactTitle": {
"position": 26
},
"Discontinued": {
"position": 23
},
"ReorderLevel": {
"position": 22
},
"RequiredDate": {
"format": {
"width": {
"num": 141,
"type": "px"
}
},
"position": 4
},
"UnitsInStock": {
"position": 20
},
"UnitsOnOrder": {
"position": 21
},
"ShipPostalCode": {
"format": {
"width": {
"num": 159,
"type": "px"
}
},
"position": 12
},
"QuantityPerUnit": {
"position": 18
}
},
"pageSize": 25,
"usePaging": false,
"aggregates": [],
"summaryOnly": false,
"showSubheaders": false,
"displayHiddenFields": true,
"showOverallAggregates": true
},
"chips": [],
"filter": {},
"useFakeData": false
},
"inputs": {
"multiInput": {
"inputs": [],
"instructions": ""
}
},
"language": "sql",
"flow": [],
"payload": "SELECT o.*, p.*, c.*\nFROM orders o\nLEFT JOIN order_details od on o.\"OrderID\" = od.\"OrderID\"\nLEFT JOIN customers c on c.\"CustomerID\" = o.\"CustomerID\"\nLEFT JOIN products p on p.\"ProductID\" = od.\"ProductID\"",
"defnUpdatedAt": "2026-01-15T16:20:00.000Z",
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": "00000000-0000-4000-8000-000000000002",
"editingId": null,
"folderId": null,
"datasource": {
"defaultLinkType": "sql",
"aiSystemMessage": "This is a PostgresSQL database. Identifiers are case-sensitive by default. \n Always surround all column names, table names, and schema names in double-quotes (\"). \n For example:\n SELECT \"OrderID\", \"ShipCountry\" FROM \"public\".\"orders\" WHERE \"ShipCity\" = 'Raleigh';\n ---",
"family": "sql",
"languages": [
"informer",
"sql",
"distinctValue",
"… 2 more items (5 total) — omitted from docs"
],
"naturalId": "admin:northwind",
"image": "/opt/informer/packages/informer-server/modules/sql/images/postgres.svg",
"compatibility": [],
"permissions": {
"assignTags": true,
"edit": true,
"delete": true,
"share": true,
"write": true,
"changeOwner": true,
"ping": true,
"scan": true,
"downloadSchema": true,
"importData": true,
"importSchema": true,
"rename": true,
"editConnection": true,
"createLink": true,
"setWrite": true,
"createSuite": true,
"createFieldExpression": true,
"createMapping": false,
"bundle": true,
"query": true
},
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"ownerId": "admin",
"slug": "northwind",
"name": "Northwind",
"description": null,
"embedded": false,
"type": "postgres",
"connection": {
"host": "localhost",
"pool": {
"max": 5,
"min": 0,
"idle": 10000,
"acquire": 10000
},
"port": 5432,
"user": "northwinduser",
"database": "northwind",
"password": "encrypted:iv:0000000000000000",
"idleTimeoutMillis": 7
},
"scannedAt": "2026-01-15T16:20:00.000Z",
"schemaUpdatedAt": "2026-01-15T16:20:00.000Z",
"rescanRequired": false,
"shared": false,
"schemas": [
"public"
],
"source": null,
"sourceId": null,
"settings": {
"multiSchema": false,
"useFakeData": false,
"remoteQueryBatchSize": {
"multiKey": 500,
"singleKey": 500
},
"usePreparedStatements": false
},
"data": null,
"appId": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"folderId": null,
"fileId": null,
"shares": []
},
"_embedded": {
"inf:query-language": {
"_links": {
"self": {
"href": "https://informer.example.com/api/query-languages/sql"
}
},
"id": "sql",
"name": "drivers:query_language.sql.name",
"description": "drivers:query_language.sql.description",
"image": "/images/query/native-sql-query.svg",
"color": "deepPurple",
"preProcessors": [
"iqlFieldIdProcessor",
null
],
"formatInputParams": null
}
}
}
When clearAllUserSettings is true (the default), the commit also clears, for
the original's embedded datasets:
- Every user's UserSettings for the Query.
- The embedded datasets' DatasetFields.
- The indexed (cached) data.
dataUpdatedAton the embedded datasets.- The JobDataset settings.
When clearAllUserSettings is false, only the Query definition is updated;
user settings and cached data are preserved, and defnUpdatedAt still advances
to track the definition change.
Breaking changes
Committing with clearAllUserSettings: true forces all users to re-run the Query
and reconfigure their views. Use false for non-breaking changes such as a
description update.
Embedded queries
For embedded queries the draft is not deleted after commit, so it persists for future edits. For ad-hoc (non-embedded) queries the draft is deleted as part of the commit.
Draft Best Practices
When to use drafts
- Schema changes - adding or removing fields, or changing data types.
- Performance tuning - testing query optimizations.
- Parameter updates - adding or modifying input parameters.
- Breaking changes - any change that invalidates cached data.
When to skip drafts
- Metadata updates - name, description, or folder changes.
- Non-breaking settings - timeout adjustments, display settings.
- Quick fixes - typos or minor corrections.
Clearing user settings
| Scenario | clearAllUserSettings |
|---|---|
| Changed field names or types | true |
| Added new fields | true |
| Changed datasource | true |
| Performance optimization (force re-fetch) | true |
| Updated description only | false |
| Changed timeout setting | false |
| Renamed Query | false |