POpolytomic
Harbors

Create Harbor Saved Query Draft

Changed on

Creates a stable Harbor saved query with its initial mutable draft.

Saved queries are supported only for Polytomic-managed Harbors whose backing Connection type is polytomic_harbor. Customer-managed Harbor backings return an unsupported-backing error.

The saved query receives a stable ID, but it remains absent from published saved-query reads until an administrator publishes its initial draft.

Use {{parameter_name}} references in sql_template. Each reference must have one scalar declaration. Validation values and defaults must match the declared string, number, boolean, date, timestamp, or uuid type.

Unknown JSON fields, including fields inside parameter declarations, return 400 Bad Request before the draft is saved. Use default_value, not default, for parameter defaults.

When you omit a parameter during execution, Polytomic uses its published default_value, never its draft validation value. An omitted optional parameter without a default binds SQL NULL. A required parameter allows omission when a default exists, but rejects explicit null even with a default.

For a report window, use a required parameter with a default so omission selects a useful window and explicit null is rejected:

{"name": "days", "type": "number", "required": true, "default_value": 7}
post/api/harbors/{harbor_id}/saved-queries

Request

  • Base URL
    https://app.polytomic.com
  • Auth
    • HTTP bearer
    • or HTTP basic

Path parameters

harbor_idstring uuid required

Unique identifier of the Harbor

Example:248df4b7-aa70-47b8-a036-33ac447e668d

Headers

X-Polytomic-Versionstring

Request body

change_notestring nullable

Optional note copied to the immutable published version

descriptionstring

Business definition and usage notes. Maximum 2,000 characters.

namestring required

Human-readable saved-query name. Maximum 200 characters.

ownerstring

Human-readable owner label. Maximum 200 characters.

sql_templatestring required

DuckDB SQL template using {{name}} references for bound parameters

validation_valuesobject nullable

Author-supplied JSON scalar values used only to validate this draft

Example request

{
  "name": "Monthly revenue",
  "owner": "Data Platform",
  "parameters": [
    {
      "name": "start_date"
    }
  ],
  "sql_template": "SELECT account_id, sum(amount) AS revenue FROM orders WHERE created_at >= {{start_date}} GROUP BY account_id"
}

Response

OK

Example response

{
  "data": {
    "created_by": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "parameters": [
      {
        "name": "start_date"
      }
    ],
    "saved_query_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "updated_by": "248df4b7-aa70-47b8-a036-33ac447e668d"
  }
}

Changes

  • d80b0fdea14eRevision changes
    • breaking

      the response's property type changed from object to no type for status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      added to the response property allOf list for the response status

  • 21557a3c149dRevision changes
    • info

      endpoint added