Fields & Parameters

Manage query fields, input parameters, and field metadata for formatting and display.

Query Fields Overview

Query fields define:

Output Schema - Fields returned by the query
Formatting - How field values are displayed
Metadata - Field types, labels, and descriptions

Fields are stored in the fields property of the query and can be scanned from the payload.fields array for datasource field resolution.

GET /api/queries/{id}/fields

Get the fields defined in a query's payload with datasource field information.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Query ID (UUID) or natural ID

Response:

{
  "_links": {
    "self": { "href": "/api/queries/{id}/fields" }
  },
  "_embedded": {
    "inf:payload-field": [
      {
        "id": "date_field",
        "name": "Sale Date",
        "type": "field",
        "fieldId": "sale_date",
        "linkRef": null,
        "_field": {
          "id": "mysql-prod:sales:sale_date",
          "datasourceId": "mysql-prod",
          "schemaId": null,
          "mappingId": "sales",
          "fieldId": "sale_date",
          "name": "sale_date",
          "type": "date",
          "datasource": {
            "id": "mysql-prod",
            "slug": "prod-mysql",
            "ownerId": "admin",
            "name": "Production MySQL"
          }
        }
      },
      {
        "id": "amount_field",
        "name": "Sale Amount",
        "type": "field",
        "fieldId": "amount",
        "_field": {
          "id": "mysql-prod:sales:amount",
          "datasourceId": "mysql-prod",
          "mappingId": "sales",
          "fieldId": "amount",
          "type": "number"
        }
      },
      {
        "id": "region_field",
        "name": "Region",
        "type": "field",
        "fieldId": "region"
      },
      {
        "id": "customer_field",
        "name": "Customer Name",
        "type": "field",
        "fieldId": "customer_name",
        "linkRef": "link_1",
        "_field": {
          "id": "mysql-prod:customers:name",
          "datasourceId": "mysql-prod",
          "mappingId": "customers",
          "fieldId": "name",
          "type": "string"
        }
      }
    ]
  },
  "start": 0,
  "count": 4,
  "total": 4
}

Field Properties:

Property	Description
`id`	Payload field identifier
`name`	Display name
`type`	Field type (typically `"field"`)
`fieldId`	Source field identifier
`linkRef`	Reference to link definition (for joined fields)
`_field`	Resolved datasource field metadata

Resolved Field Metadata:

Property	Description
`id`	Full datasource field ID (`datasourceId:mappingId:fieldId`)
`datasourceId`	Source datasource UUID
`schemaId`	Schema identifier (for databases with schemas)
`mappingId`	Table/mapping identifier
`fieldId`	Column/field identifier
`type`	Data type (`string`, `number`, `date`, `boolean`)
`datasource`	Embedded datasource object

Field Resolution

The endpoint scans payload.fields and resolves each field to its datasource definition. Fields from joined tables use linkRef to determine the linked datasource and mapping.

DELETE /api/queries/{id}/fields

Remove all field definitions from a query's payload.

Authentication: Required Permission: query:write

Path Parameters:

Parameter	Type	Description
`id`	string	Query ID (UUID) or natural ID

Response:

Returns 204 No Content on success.

Field Removal

This removes the fields array from the query's payload, not the fields formatting object. To clear formatting, use PUT /api/queries/{id} with fields: null.

Input Parameters

Input parameters allow queries to accept dynamic values at runtime. They are defined in the inputs property of the query.

Input Definition Structure

{
  "inputs": {
    "startDate": {
      "type": "date",
      "label": "Start Date",
      "description": "Beginning of date range",
      "default": "2024-01-01",
      "required": true,
      "options": null
    },
    "region": {
      "type": "string",
      "label": "Sales Region",
      "description": "Filter by region",
      "default": "All",
      "required": false,
      "options": ["West", "East", "North", "South", "All"]
    },
    "minAmount": {
      "type": "number",
      "label": "Minimum Amount",
      "default": 0,
      "required": false
    }
  }
}

Input Properties:

Property	Type	Description
`type`	string	Input type: `string`, `number`, `date`, `boolean`, `datetime`
`label`	string	Display label for UI
`description`	string	Help text
`default`	any	Default value
`required`	boolean	Whether input is required
`options`	array	List of allowed values (for dropdowns)

Parameter Usage in Queries

Parameters are referenced in query payloads using language-specific syntax:

SQL:

{
  "language": "sql",
  "payload": {
    "sql": "SELECT * FROM sales WHERE date >= :startDate AND region = :region"
  },
  "inputs": {
    "startDate": { "type": "date", "label": "Start Date" },
    "region": { "type": "string", "label": "Region" }
  }
}

i5-QL:

{
  "language": "i5-ql",
  "payload": {
    "filters": [
      { "field": "date", "operator": ">=", "value": { "param": "startDate" } }
    ]
  },
  "inputs": {
    "startDate": { "type": "date", "label": "Start Date" }
  }
}

GET /api/queries/{id}/input-templates

Get input parameter templates for a query based on its language.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Query ID (UUID) or natural ID

Response:

Returns language-specific input templates and suggestions.

{
  "suggested": [
    {
      "name": "startDate",
      "type": "date",
      "label": "Start Date",
      "description": "Beginning of date range"
    },
    {
      "name": "endDate",
      "type": "date",
      "label": "End Date",
      "description": "End of date range"
    }
  ],
  "common": [
    {
      "name": "limit",
      "type": "number",
      "label": "Row Limit",
      "default": 1000
    },
    {
      "name": "offset",
      "type": "number",
      "label": "Offset",
      "default": 0
    }
  ]
}

Template Discovery

Use this endpoint to discover recommended parameter names and types for a query language. The suggestions are based on common patterns and query analysis.

Field Formatting

The fields property (separate from payload.fields) stores formatting metadata for display:

{
  "fields": {
    "sale_date": {
      "format": "MM/DD/YYYY",
      "label": "Sale Date",
      "align": "left"
    },
    "amount": {
      "format": "$0,0.00",
      "label": "Amount",
      "align": "right",
      "color": {
        "rules": [
          {
            "condition": { "operator": "<", "value": 0 },
            "color": "#ff0000"
          },
          {
            "condition": { "operator": ">", "value": 1000 },
            "color": "#00ff00"
          }
        ]
      }
    },
    "region": {
      "format": "uppercase",
      "label": "Region"
    }
  }
}

Format Options:

Field Type	Format Examples
Date	`MM/DD/YYYY`, `YYYY-MM-DD`, `DD-MMM-YY`
Number	`0,0.00`, `$0,0.00`, `0.00%`, `0a` (abbreviated)
String	`uppercase`, `lowercase`, `capitalize`
Boolean	`Yes/No`, `True/False`, `1/0`

Formatting Properties:

Property	Type	Description
`format`	string	Format string (type-specific)
`label`	string	Display label
`align`	string	Alignment: `left`, `center`, `right`
`color`	object	Conditional coloring rules
`width`	integer	Column width (pixels)
`hidden`	boolean	Hide field in default view

Updating Field Formatting

Use PUT /api/queries/{id} to update field formatting:

{
  "fields": {
    "sale_date": {
      "format": "YYYY-MM-DD",
      "label": "Date"
    },
    "amount": {
      "format": "$0,0.00",
      "color": {
        "rules": [
          { "condition": { "operator": "<", "value": 0 }, "color": "red" }
        ]
      }
    }
  }
}

Field Settings

The settings property can store field-specific configuration:

{
  "settings": {
    "fieldDefaults": {
      "dateFormat": "MM/DD/YYYY",
      "numberFormat": "0,0.00"
    },
    "fieldOrder": ["date", "region", "amount", "customer"],
    "hiddenFields": ["internal_id", "created_at"],
    "timeout": 60000
  }
}

Common Settings:

Setting	Type	Description
`fieldDefaults`	object	Default formats for field types
`fieldOrder`	array	Default field display order
`hiddenFields`	array	Fields to hide by default
`timeout`	integer	Query execution timeout (ms)

GET /api/queries/{id}/settings

Get query-specific settings including field defaults.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Query ID (UUID) or natural ID

Response:

Returns the query's settings object merged with user-specific settings.

{
  "fieldDefaults": {
    "dateFormat": "MM/DD/YYYY"
  },
  "timeout": 60000,
  "userSettings": {
    "params": {
      "startDate": "2024-01-01"
    }
  }
}

PUT /api/queries/{id}/settings

Update query settings.

Authentication: Required Permission: query:write

Path Parameters:

Parameter	Type	Description
`id`	string	Query ID (UUID) or natural ID

Request Body:

{
  "fieldDefaults": {
    "dateFormat": "YYYY-MM-DD",
    "numberFormat": "$0,0.00"
  },
  "timeout": 120000,
  "fieldOrder": ["date", "amount", "region"]
}

Response:

Returns the updated settings object.

Settings vs Fields

Use settings for query-level configuration and defaults
Use fields for field-specific formatting and display rules
Settings apply to all instances; field formatting is per-field

POST /api/queries/{id}/settings/_restore

Restore query settings to defaults.

Authentication: Required Permission: query:write

Path Parameters:

Parameter	Type	Description
`id`	string	Query ID (UUID) or natural ID

Response:

Returns the restored default settings.

{
  "fieldDefaults": {},
  "timeout": 60000
}

Reset Scope

This only resets the query's settings object. Field formatting (fields) and user-specific settings are not affected.

Best Practices

Input Parameters

Use Descriptive Names - startDate not sd, customerRegion not reg
Provide Defaults - Always set sensible default values
Add Descriptions - Help users understand parameter purpose
Use Options - Provide dropdown options when values are constrained
Mark Required - Clearly indicate which parameters are mandatory

Field Formatting

Consistent Formats - Use the same date/number formats across related queries
Conditional Coloring - Highlight important values (negative amounts, overdue dates)
Appropriate Alignment - Numbers right-aligned, text left-aligned
Hide Noise - Hide technical fields users don't need to see
Label Everything - Use friendly labels instead of field names

Performance

Limit Field Resolution - Only resolve fields when needed
Cache Format Strings - Reuse format strings across fields
Avoid Heavy Computation - Don't compute formatting in query payload
Use Field Defaults - Set defaults in settings rather than per-field

Query Fields Overview​

GET /api/queries/{id}/fields​

DELETE /api/queries/{id}/fields​

Input Parameters​

Input Definition Structure​

Parameter Usage in Queries​

GET /api/queries/{id}/input-templates​

Field Formatting​

Updating Field Formatting​

Field Settings​

GET /api/queries/{id}/settings​

PUT /api/queries/{id}/settings​

POST /api/queries/{id}/settings/_restore​

Best Practices​

Input Parameters​

Field Formatting​

Performance​

Query Fields Overview

GET /api/queries/{id}/fields

DELETE /api/queries/{id}/fields

Input Parameters

Input Definition Structure

Parameter Usage in Queries

GET /api/queries/{id}/input-templates

Field Formatting

Updating Field Formatting

Field Settings

GET /api/queries/{id}/settings

PUT /api/queries/{id}/settings

POST /api/queries/{id}/settings/_restore

Best Practices

Input Parameters

Field Formatting

Performance