API docs by Redocly

Imply Polaris API (1.0.0)

Download OpenAPI specification:Download

You can use the Imply Polaris API to programmatically manage your tables, files, and ingestion tasks. See API overview for information and examples on how to get started.

Polaris API resources

Polaris API resources are either global or regional.

Global resources

You can access a global resource irrespective of the cloud provider or region in which Polaris hosts your project.

Global resources are relative to the base URL https://ORGANIZATION_NAME.api.imply.io, where ORGANIZATION_NAME is the custom domain through which you access Polaris.

The Polaris API supports the following global resources:

Regional resources

A regional resource is only accessible in the cloud and region where Polaris hosts your project. You must specify the project's cloud provider and region to call a regional resource. For more information, see Cloud providers and regions.

Regional resources are relative to the base URL https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io/v1/projects/PROJECT_ID.

Replace the following:

  • ORGANIZATION_NAME: Custom domain through which you access Polaris.
  • REGION: Cloud region of your Polaris project.
  • CLOUD_PROVIDER: Cloud provider for your Polaris project.
  • PROJECT_ID: Unique identifier for your Polaris project.

For example: https://example.us-east-1.aws.api.imply.io/v1/projects/12375ffx-f7x4-4f0x-a1a6-3b3424987ee0/files.

The Polaris API supports the following regional resources:

For projects created after September 29, 2023, the Collections, Embedding, Events, Files, and Query APIs require the project ID in the base URL. We strongly recommend updating your regional API calls for existing projects to include the project ID prior to September 2024. See the API migration guide for more information.

Deprecated resources

The following Polaris API resources are deprecated. Instead, use the suggested replacements.

Deprecated resource Replacement Deprecation date Removal date
Connections v2 Connections v1 September 2023 September 2024
Embedding v1 Embedding links v1 February 2024 September 2024
Jobs v2 Jobs v1 September 2023 September 2024
Project v1 Projects v1 September 2023 September 2024
Tables v2 Tables v1 September 2023 September 2024

For more information, see Migration guide for deprecated APIs.

Status and error codes

Imply uses conventional HTTP response codes to indicate success or failure of a Polaris API request. In general:

  • Codes in the 2xx range indicate success.
  • Codes in the 4xx range indicate an error that failed due to the information supplied in the request—for example, a required parameter is missing.
  • Codes in the 5xx range indicate an error with the Imply servers.

Some of the most commonly received status codes are as follows:

Code Description
200 - OK Successful request.
400 - Bad request The request was unacceptable, often due to missing a required parameter. The response usually contains information about the problem and how to resolve it.
401 - Unauthorized Valid OAuth credentials not found. See Authenticate API requests for information on obtaining credentials for Polaris API requests.
403 - Forbidden The supplied user credentials don't have permissions to perform the request.
404 - Not found The requested resource doesn't exist.
409 - Conflict The request can't complete—for example, due to a conflict with the current state of the target resource.
429 - Too many requests Too many requests hit the API too quickly. For push streaming requests the response contains details on how many requests you can send in a defined period and how long to wait until retry.
500, 502, 504 - Server errors Something went wrong at the Imply end. These are rare. Contact Polaris Support.
503 - Service unavailable Polaris is temporarily unavailable, usually for scheduled maintenance.

For more information see the official HTTP status code definitions.

Connections v1

Manage connections to external sources of data.

List all connections

Returns all existing connections.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connections belong.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a connection

Creates a new connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connections belong.

Request Body schema: application/json
required

A connection to be created.

container
required
string

Name of the container in the specified storage account in Azure Blob Storage.

name
required
string (ConnectionNamePayload) [ 1 .. 64 ] characters

Name of the connection. A connection name can only contain ASCII letters, numbers, and the following characters: ., _, -. The maximum length of a connection name is 64.

required
object (ConnectionSecretsRequiredPayload)

Type of connection secrets. The following secrets types are supported:

  • access_key: Access key to authenticate Azure Blob Storage or AWS S3 connections.
  • aws_iam: AWS IAM role assumption. Supported for Kafka (MSK) connections.
  • basic: Basic access authentication. Select this type for SQL connections or when you use a Confluent Schema Registry API key and secret.
  • confluent: Deprecated. For Confluent connections only. Instead use sasl_plain.
  • sas_token: Shared access signature (SAS) token for Azure Blob Storage.
  • sasl_plain: Authentication mechanism of SASL/PLAIN. Supported for Kafka and Confluent Cloud connections.
  • sasl_scram: Authentication mechanism of SASL/SCRAM. Supported for Kafka connections.
storageAccount
required
string

Name of the storage account in Azure Blob Storage.

type
required
string (ConnectionTypePayload)

Connection type. For reference on the information required for each connection type, see Create a connection.

description
string (ConnectionDescriptionPayload)

Optional description for the connection.

prefix
string

Prefix to restrict the connection to specific blobs.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example-connection",
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Response samples

Content type
application/json
Example
{
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2019-08-24T14:15:22Z",
  • "name": "example-connection",
  • "submittedByUser": {
    },
  • "submittedOnTimestamp": "2019-08-24T14:15:22Z",
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Get connection details

Returns information for a single connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string (ConnectionNamePayload) [ 1 .. 64 ] characters
Example: example-connection

The name of the connection to get.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connection belongs.

Responses

Response samples

Content type
application/json
Example
{
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2019-08-24T14:15:22Z",
  • "name": "example-connection",
  • "submittedByUser": {
    },
  • "submittedOnTimestamp": "2019-08-24T14:15:22Z",
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Update a connection

Updates details for a specific connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

The name of the connection to update.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connection belongs.

Request Body schema: application/json
required

The updated connection spec.

type
required
string (ConnectionTypePayload)

Connection type. For reference on the information required for each connection type, see Create a connection.

container
string

Name of the container in the specified storage account in Azure Blob Storage.

description
string (ConnectionDescriptionPayload)

Optional description for the connection.

prefix
string

Prefix to restrict the connection to specific blobs.

object (ConnectionSecretsOptionalPayload)

Type of connection secrets. The following secrets types are supported:

  • access_key: Access key to authenticate Azure Blob Storage or AWS S3 connections.
  • aws_iam: For AWS IAM role assumption. Supported for MSK (Kafka) connections.
  • basic: Basic access authentication. Select this type for SQL connections or when you use a Confluent Schema Registry API key and secret.
  • confluent: Deprecated. For Confluent connections only. Instead use sasl_plain.
  • sas_token: Shared access signature (SAS) token for Azure Blob Storage.
  • sasl_plain: Authentication mechanism of SASL/PLAIN. Supported for Kafka and Confluent Cloud connections.
  • sasl_scram: Authentication mechanism of SASL/SCRAM. Supported for Kafka connections.
storageAccount
string

Name of the storage account in Azure Blob Storage.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Response samples

Content type
application/json
Example
{
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2019-08-24T14:15:22Z",
  • "name": "example-connection",
  • "submittedByUser": {
    },
  • "submittedOnTimestamp": "2019-08-24T14:15:22Z",
  • "type": "azure",
  • "description": "string",
  • "storageAccount": "my-account",
  • "container": "demo-container",
  • "prefix": "project/files/",
  • "secrets": {
    }
}

Delete a connection

Deletes an existing connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

The name the connection to delete.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connection belongs.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Test a connection

Checks whether an existing connection is valid.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

The name of the connection to test.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the connection belongs.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Get meta information from connection

Returns meta information related to connections.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the meta information related to connections belongs.

Responses

Response samples

Content type
application/json
{
  • "externalId": "123e4567-e89b-12d3-a456-426614174000",
  • "implyArn": "arn:aws:iam::123456789012:role/imply-cluster-1234567"
}

Events v1

Push data from an application source through a push_streaming connection.

Push events to a Polaris connection

Sends data from an application source to a Polaris connection.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
connectionName
required
string

The name of the connection to push data to. Note that for legacy tables created via the v1 API, the connection name is named after the table ID.

projectId
required
string

The project ID for the request.

Request Body schema:
string <byte> (EventRequest)

Data to push to the Polaris table.

See Supported data and file formats for the data formats that Polaris supports for streaming ingestion.

The event data must include a timestamp value. For more information on event payload requirements, see Push event data by API.

Responses

Request samples

Content type
"{\"__time\":\"2022-04-16T00:46:58.771Z\",\"channel\":\"#en.wikipedia\",\"user\":\"GELongstreet\",\"added\":36,\"deleted\":0}\n{\"__time\":\"2022-04-17T04:07:28.781Z\",\"channel\":\"#de.wikipedia\",\"user\":\"Kolega2357\",\"added\":13,\"deleted\":16}"

Files v1

Upload, list, and delete files.

List files

List files.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project containing the files.

query Parameters
paginationLimit
integer [ 1 .. 1000 ]
Default: 1000

A result limit for pagination.

paginationOffset
integer >= 0
Default: 0

A result offset for pagination.

searchString
string

Filter the results to only include files that have the provided string contained within one of their fields.

sortColumn
string (FileSortColumn)
Default: "uploaded_on_dt"
Enum: "compression_format" "data_format" "digest_algo" "digest_hash" "name" "size_bytes" "uploaded_by_user_name" "uploaded_on_dt"

The column to sort file results by.

sortOrder
string (SortOrder)
Default: "DESC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order to sort file results by.

Responses

Response samples

Content type
application/json
{
  • "files": [
    ],
  • "links": {
    },
  • "space": {
    },
  • "totalCount": 0
}

Upload a file

Uploads a file to the Polaris staging area.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project containing the files.

query Parameters
compressionFormat
string (CompressionFormat)
Enum: "none" "bz2" "gz" "sz" "xz" "zstd"
Example: compressionFormat=gz

If specified, the compression used for the file. Otherwise, Polaris infers the compression from the filename or the Content-Type HTTP header in the multipart form request.

Supported compression formats:

dataFormat
string (DataFormat)
Enum: "avro_ocf" "avro_stream" "csv" "kafka" "kinesis" "nd-json" "orc" "parquet" "protobuf"
Example: dataFormat=nd-json

If specified, the format of the data. Otherwise, Polaris infers the data format from the filename or the Content-Type HTTP header in the multipart form request.

For more information on supported data formats, see Supported data and file formats.

Request Body schema: multipart/form-data

A multipart/form-data request containing a single part with the file to be uploaded. You should not set the Content-Type: multipart/form-data header explicitly. Allow your client to assign the header automatically because it will also properly set the associated boundary directive.

The total size of the request including the file, HTTP headers, etc. must be less than 10 GB. This limit refers to the size of the file transmitted by the browser or HTTP client. You may upload a file that's larger than 10 GB on disk if your browser or client compresses the file in transit to below 10 GB.

File names must be unique. You cannot upload two files with the same name to Polaris.

file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "compressionFormat": "gz",
  • "dataFormat": "nd-json",
  • "digest": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "weather/20210603/01/hourly.json",
  • "sizeBytes": 207394342360,
  • "uploadedBy": {
    },
  • "uploadedOnDatetime": "2021-09-07T05:02:24Z"
}

Get file details

Returns information for a single file.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

Name of the file (may contain slashes)

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the file belongs.

Responses

Response samples

Content type
application/json
{
  • "compressionFormat": "gz",
  • "dataFormat": "nd-json",
  • "digest": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "weather/20210603/01/hourly.json",
  • "sizeBytes": 207394342360,
  • "uploadedBy": {
    },
  • "uploadedOnDatetime": "2021-09-07T05:02:24Z"
}

Delete a file

Deletes a file.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
name
required
string

Name of the file (may contain slashes)

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project where the file belongs.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Lookups v1

Create and manage lookups for Imply Polaris. See Lookups for more details about lookups and how to manage lookups in the Polaris UI.

List all lookups

Returns all lookups in a specified project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a lookup

Creates a lookup in a specified project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Request Body schema: application/json
required

A lookup to be created.

name
required
string

Unique name of the lookup.

required
object (LookupSourcePayload)

The source of a lookup. The following lookup type is supported:

  • table: A lookup source that references a table. The table must be partitioned by ALL granularity and contain a single segment.

Responses

Request samples

Content type
application/json
{
  • "name": "my-lookup-name",
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "name": "my-lookup-name",
  • "source": {
    }
}

Get lookup details

Returns details for a specified lookup.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "name": "my-lookup-name",
  • "source": {
    }
}

Update a lookup

Updates the details of a specified lookup.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Request Body schema: application/json
required

The updated lookup request.

required
object (LookupSourcePayload)

The source of a lookup. The following lookup type is supported:

  • table: A lookup source that references a table. The table must be partitioned by ALL granularity and contain a single segment.

Responses

Request samples

Content type
application/json
{
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "name": "my-lookup-name",
  • "source": {
    }
}

Delete a lookup

Deletes a lookup in a specified project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

List all aliases for a lookup

Returns all aliases for a specified lookup.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create or update aliases for a lookup

Create or update the aliases for a specified lookup. You must provide the details of all aliases you want to retain for the lookup, even if you don't want to update them. Polaris recreates the lookup's aliases with the details you specify in the request. Polaris creates a new alias if the supplied alias name doesn't exist.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
lookupName
required
string

The name of a lookup.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Request Body schema: application/json
required

A lookup alias to be created or updated.

required
Array of objects (LookupAliasPayload)

Responses

Request samples

Content type
application/json
{
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Jobs v1

Manage jobs in Imply Polaris.

List all jobs

Returns all jobs.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the project where the tables belong.

query Parameters
connectionName
Array of strings (ConnectionNamePayload) [ items [ 1 .. 64 ] characters ]
Example: connectionName=example-connection

The connection to filter jobs by.

executionStatus
Array of strings (JobExecutionStatusV2)
Items Enum: "pending" "running" "completed" "idle" "canceled" "failed" "suspended" "unknown"

Filters results with a certain execution status. For example, to list running jobs only, use the address /v1/projects/{projectId}/jobs?executionStatus=running.

healthStatus
Array of strings (JobHealthStatusV2)
Items Enum: "ok" "warn" "error"

Filters results with a certain health status. For example, to list jobs with warnings or errors, use the address /v1/projects/{projectId}/jobs?healthStatus=warn&healthStatus=error.

paginationLimit
integer [ 1 .. 1000 ]
Default: 100

A result limit for pagination.

paginationOffset
integer >= 0
Default: 0

A result offset for pagination.

searchString
string

Filter results to those jobs where the given string is contained in one of the job's fields.

sortColumn
string (JobSortSearchColumn)
Default: "last_updated_date_time"
Enum: "created_by_user_name" "created_date_time" "execution_status" "last_updated_date_time" "source_name" "source_type" "source_connection_name" "source_table_name" "target_table_name" "type"

Sort results by one of the following fields:

  • created_by_user_name : User that created the job.
  • created_date_time : Date the job was created.
  • execution_status : Job's execution status.
  • last_updated_date_time : Date the job was last updated.
  • source_name : Job's source name, such as a connection name.
  • source_type : Job's source type, such as connection or table.
  • source_connection_name : Deprecated, use source_name instead.
  • source_table_name : Deprecated, use source_name instead.
  • target_table_name : Table that the job targets.
  • type : Job type.
sortOrder
string (SortOrder)
Default: "DESC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order to sort job results by.

targetTableId
string <uuid> (TableId)

Filters results for jobs associated with a particular target table id.

targetTableName
string (TableName) [ 1 .. 255 ] characters
Example: targetTableName=example-table

Filters results for jobs associated with a particular target table name.

type
Array of strings (JobTypeV2)
Items Enum: "batch" "delete_data" "drop_table" "restore_data" "streaming" "sql"
Example: type=batch

Filters results with a certain job type. For example, to select batch and streaming jobs, use the address /v1/projects/{projectId}/jobs?type=batch&type=streaming.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "moreResultsAvailable": true
}

Create a job

Creates a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the project where the tables belong.

Request Body schema: application/json
required

A job to be created.

required
object (JobSourceV2)

Source input of the job.

required
object (JobTargetV2)

Target output of the job.

type
required
string (JobTypeV2)
Default: "sql"

Type of job:

  • batch - A batch ingestion job.
  • delete_data - A job to delete data within a table.
  • drop_table - A job to delete a table and all of its data.
  • restore_data - A job to restore deleted data in a table.
  • streaming - A streaming ingestion job.
  • sql - A SQL-based ingestion job.

You can't drop a table that's used as a lookup source.

For information about ingestion jobs, see Create an ingestion job and Ingest using SQL.

clusteringColumns
Array of strings (ClusteringColumns)

Optional columns to use for clustering. If specified, will take precedence over clustering columns defined on a table. Polaris sorts columns within a partition based on their order in this array.

For jobs targeting aggregate tables, only dimensions (not measures) are supported for clustering.

For more information, see Clustering.

object

Context parameters used to specify various query configuration parameters. For more information, see SQL ingestion reference.

createTableIfNotExists
boolean
Default: false

Whether the job should create the table if it doesn't already exist. For more information, see Introduction to tables.

filterExpression
string

SQL expression to use for filtering the source data. For more information, see Filter data to ingest.

ingestionMode
string (IngestionModeV2)
Default: "append"
Enum: "append" "replace"

Mode of ingestion:

  • append - Append newly ingested data to the existing data. To ingest a certain time range of source data, apply a filter expression to filter by a given time interval.
  • replace - Overwrite existing data for specific time intervals or all data in the table. Specify specific time intervals in target.intervals, or set "replaceAll": true. To restrict the time interval of what data Polaris ingests, use filter expressions.
Array of objects (InputToTableSchemaMappingsV2)
Default: []

Relationship between the input fields and the output columns of a table's schema. Define the Polaris column name in columnName, and specify how the column is defined with respect to the input fields in expression. expression must be a valid SQL expression.

For batch ingestion jobs, you must include a mapping for each field. Polaris ignores unmapped input fields. Streaming ingestion jobs may apply schema auto-discovery for Polaris to discover input fields and map them directly to table dimensions. Always specify a mapping for __time and when you want to transform an input field.

For more information, see Map and transform data with input expressions and Schema auto-discovery on ingestion jobs.

maxParseExceptions
integer
Default: 2147483647

Configuration parameter that specifies the maximum number of parse exceptions that a task can tolerate before failing.

partitionedBy
string (PartitioningGranularity)
Enum: "second" "minute" "five_minute" "ten_minute" "fifteen_minute" "thirty_minute" "hour" "six_hour" "eight_hour" "day" "month" "quarter" "year" "all"

Optional time partitioning. If specified, takes precedence over the time partitioning defined on the target table. If unspecified, defaults to the time partitioning of the table.

When ingesting into a lookup table, you can only set all partitioning.

replaceAll
boolean
Default: false

Replace all data with this job. Don't set this to true when the job's ingestion mode is append or when target.intervals is specified.

Responses

Request samples

Content type
application/json
Example
{
  • "type": "batch",
  • "source": {
    },
  • "target": {
    },
  • "context": { },
  • "clusteringColumns": [
    ],
  • "createTableIfNotExists": false,
  • "filterExpression": "\"dimension\" > 0",
  • "ingestionMode": "append",
  • "mappings": [
    ],
  • "maxParseExceptions": 2147483647,
  • "partitionedBy": "day",
  • "replaceAll": false
}

Response samples

Content type
application/json
Example
{
  • "createdBy": {
    },
  • "createdTimestamp": "2021-06-06T00:00:00.000Z",
  • "desiredExecutionStatus": "running",
  • "executionStatus": "pending",
  • "health": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "lastModifiedBy": {
    },
  • "lastUpdatedTimestamp": "2021-06-06T00:00:00.000Z",
  • "spec": {
    },
  • "target": {
    },
  • "type": "batch",
  • "completedTimestamp": "2021-06-06T00:00:00.000Z",
  • "startedTimestamp": "2021-06-06T00:00:00.000Z",
  • "source": {
    },
  • "context": { },
  • "filterExpression": "\"dimension\" > 0",
  • "ingestionMode": "append",
  • "mappings": [
    ],
  • "maxParseExceptions": 2147483647,
  • "query": "string"
}

Get job details

Returns information for a single job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
Example
{
  • "createdBy": {
    },
  • "createdTimestamp": "2021-06-06T00:00:00.000Z",
  • "desiredExecutionStatus": "running",
  • "executionStatus": "pending",
  • "health": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "lastModifiedBy": {
    },
  • "lastUpdatedTimestamp": "2021-06-06T00:00:00.000Z",
  • "spec": {
    },
  • "target": {
    },
  • "type": "batch",
  • "completedTimestamp": "2021-06-06T00:00:00.000Z",
  • "startedTimestamp": "2021-06-06T00:00:00.000Z",
  • "source": {
    },
  • "context": { },
  • "filterExpression": "\"dimension\" > 0",
  • "ingestionMode": "append",
  • "mappings": [
    ],
  • "maxParseExceptions": 2147483647,
  • "query": "string"
}

Update a job

Updates the execution status of a job.

Although you can continue to use this PUT request to update a job's status, it's recommended to use the POST request to the job status endpoint.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Request Body schema: application/json
required

The job to be updated.

desiredExecutionStatus
required
string (DesiredJobExecutionStatusV2)
Default: "running"
Enum: "running" "canceled" "suspended"

Desired execution status of the job. This field only applies to updating an ingestion job and is ignored when creating jobs. You cannot update a deletion job. The default desired execution status is running for jobs that should run to completion. Otherwise, specify the value canceled to cancel an ingestion job. If an unsupported value is supplied, Polaris raises a 400 Bad Request error.

Responses

Request samples

Content type
application/json
{
  • "desiredExecutionStatus": "running"
}

Response samples

Content type
application/json
Example
{
  • "createdBy": {
    },
  • "createdTimestamp": "2021-06-06T00:00:00.000Z",
  • "desiredExecutionStatus": "running",
  • "executionStatus": "pending",
  • "health": {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "lastModifiedBy": {
    },
  • "lastUpdatedTimestamp": "2021-06-06T00:00:00.000Z",
  • "spec": {
    },
  • "target": {
    },
  • "type": "batch",
  • "completedTimestamp": "2021-06-06T00:00:00.000Z",
  • "startedTimestamp": "2021-06-06T00:00:00.000Z",
  • "source": {
    },
  • "context": { },
  • "filterExpression": "\"dimension\" > 0",
  • "ingestionMode": "append",
  • "mappings": [
    ],
  • "maxParseExceptions": 2147483647,
  • "query": "string"
}

Get job overall progress

Returns progress for a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "overallProgress": 0.1
}

Get job logs

Returns logs for a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "logs": [
    ]
}

Get job metrics

Returns detailed metrics about a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job for which to get the metadata.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "totals": {
    }
}

Reset job to apply streaming ingestion offset

Resets a streaming ingestion job. This resets the point from which Polaris ingests streaming data to readFromPoint set in current streaming ingestion jobs. Only applies when there was a previous streaming ingestion job that used the same topic or stream name for the same target table. For more information, see Reset streaming job offset.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

The server-generated ID of the job

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Get job execution status

Returns the execution status for a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

Server-generated job ID.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Responses

Response samples

Content type
application/json
{
  • "executionStatus": "pending"
}

Update job execution status

Updates the execution status of a job.

Use this request to cancel any ingestion job in progress or to suspend and resume a streaming ingestion job.

You can't update data deletion jobs.

Prefer this method over Updating a job.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
jobId
required
string <uuid> (JobIdPayload)

Server-generated job ID.

projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The project ID where the tables belong.

Request Body schema: application/json
required

A request to update the job's execution status.

desiredExecutionStatus
required
string (DesiredJobExecutionStatusV2)
Default: "running"
Enum: "running" "canceled" "suspended"

Desired execution status of the job. This field only applies to updating an ingestion job and is ignored when creating jobs. You cannot update a deletion job. The default desired execution status is running for jobs that should run to completion. Otherwise, specify the value canceled to cancel an ingestion job. If an unsupported value is supplied, Polaris raises a 400 Bad Request error.

Responses

Request samples

Content type
application/json
{
  • "desiredExecutionStatus": "running"
}

Response samples

Content type
application/json
{
  • "executionStatus": "pending"
}

Query v1

Submit and manage queries.

The Query API has resources to perform synchronous or asynchronous queries. Synchronous (sync) queries are short running (highly concurrent) and low latency. Asynchronous (async) queries are long running, high latency, and high throughput.

Sync queries target precached data including real-time streaming data. Async queries target all data, including any data only in deep storage. Data only in deep storage is offloaded from precache due to one or more cached storage policies. To add or update a storage policy on a table, see storagePolicy in Update a table.

You can query data that's already ingested into Imply Polaris. You can't use the Query API for ingesting data. To ingest data, see Create a job.

For a guide on querying data, see Query data by API.

Polaris projects created after July 1, 2024 have the async query feature enabled by default. If your project was created before July 1, 2024, contact your Polaris support representative to enable the feature.

Query precached data

Submits a SQL query against precached data including real-time streaming data. Returns a JSON object with the query results.

This request does not query data that’s offloaded from precache and only in deep storage. Polaris directly returns query results in the HTTP response body.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

Request Body schema: application/json
required

The SQL query and additional properties to control query execution and result format.

query
required
string

The SQL query.

object

JSON object containing optional SQL query context parameters, such as to set the query ID, time zone, and whether to use an approximation algorithm for distinct count. For supported parameters, see Druid SQL query context.

header
boolean
Default: false

Boolean value that determines whether to return information on column names. When set to true, Polaris returns the column names as the first row of the results. To also get information on the column types, set typesHeader or sqlTypesHeader to true.

parameters
Array of objects

List of Druid SQL query parameters for parameterized queries. Each parameter in the array should be a JSON object containing the parameter's SQL data type and parameter value.

For example, the following query returns results with timestamps later than 2019-08-21 00:00:00:

{
  "query": "SELECT \"col1\" FROM \"myTable\" WHERE __time > ? AND ARRAY_CONTAINS(?, \"col1\")",
  "parameters": [
    {
      "type": "TIMESTAMP",
      "value": "2019-08-21 00:00:00"
    },
    {
      "type": "ARRAY",
      "value": [-25.7, null, 36.85]
    }
  ]
}
resultFormat
string (ResultFormat)
Default: "object"
Enum: "object" "array" "objectLines" "arrayLines" "csv"

String that indicates the format to return query results. Select one of the following formats:

  • object: Returns a JSON array of JSON objects with the HTTP response header Content-Type: application/json. Object field names match the columns returned by the SQL query in the same order as the SQL query.

  • array: Returns a JSON array of JSON arrays with the HTTP response header Content-Type: application/json. Each inner array has elements matching the columns returned by the SQL query, in order.

  • objectLines: Returns newline-delimited JSON objects with the HTTP response header Content-Type: text/plain. Newline separation facilitates parsing the entire response set as a stream if you don't have a streaming JSON parser. This format includes a single trailing newline character so you can detect a truncated response.

  • arrayLines: Returns newline-delimited JSON arrays with the HTTP response header Content-Type: text/plain. Newline separation facilitates parsing the entire response set as a stream if you don't have a streaming JSON parser. This format includes a single trailing newline character so you can detect a truncated response.

  • csv: Returns comma-separated values with one row per line. Sent with the HTTP response header Content-Type: text/csv.

    Druid uses double quotes to escape individual field values. For example, a value with a comma returns "A,B". If the field value contains a double quote character, Druid escapes it with a second double quote character. For example, foo"bar becomes foo""bar. This format includes a single trailing newline character so you can detect a truncated response.

sqlTypesHeader
boolean
Default: false

Adds SQL type information in the header. Requires header to be set to true. For compatibility, Druid returns the HTTP header X-Druid-SQL-Header-Included: yes when all of the following conditions are met:

  • The header property is set to true.
  • The version of Druid supports typesHeader and sqlTypesHeader, regardless of whether either property is set.
typesHeader
boolean
Default: false

Adds runtime type information in the header. Requires header to be set to true. Complex types, like sketches, will be reported as COMPLEX<typeName> if a particular complex type name is known for that field, or as COMPLEX if the particular type name is unknown or mixed.

Responses

Request samples

Content type
application/json
{
  • "query": "SELECT \"__time\", \"val\" FROM \"polaris_table\" WHERE \"foo\" = 'bar'",
  • "resultFormat": "array",
  • "header": false,
  • "typesHeader": false,
  • "sqlTypesHeader": false,
  • "context": {
    },
  • "parameters": [
    ]
}

Response samples

Content type
application/json
[
  • [
    ]
]

Query all data asynchronously

Submits a SQL query against real-time data as well as data in deep storage.

Queries precached data as well as data offloaded from precache. The response body doesn't return query results. To get query results, see Get results for an async query.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

Request Body schema: application/json
required

The SQL query and additional properties to control query execution and result format.

query
required
string

The SQL query.

object

JSON object containing optional SQL query context parameters, such as to set the query ID, time zone, and whether to use an approximation algorithm for distinct count. For supported parameters, see Druid SQL query context.

header
boolean
Default: false

Boolean value that determines whether to return information on column names. When set to true, Polaris returns the column names as the first row of the results. To also get information on the column types, set typesHeader or sqlTypesHeader to true.

parameters
Array of objects

List of Druid SQL query parameters for parameterized queries. Each parameter in the array should be a JSON object containing the parameter's SQL data type and parameter value.

For example, the following query returns results with timestamps later than 2019-08-21 00:00:00:

{
  "query": "SELECT \"col1\" FROM \"myTable\" WHERE __time > ? AND ARRAY_CONTAINS(?, \"col1\")",
  "parameters": [
    {
      "type": "TIMESTAMP",
      "value": "2019-08-21 00:00:00"
    },
    {
      "type": "ARRAY",
      "value": [-25.7, null, 36.85]
    }
  ]
}
resultFormat
string (ResultFormat)
Default: "object"
Enum: "object" "array" "objectLines" "arrayLines" "csv"

String that indicates the format to return query results. Select one of the following formats:

  • object: Returns a JSON array of JSON objects with the HTTP response header Content-Type: application/json. Object field names match the columns returned by the SQL query in the same order as the SQL query.

  • array: Returns a JSON array of JSON arrays with the HTTP response header Content-Type: application/json. Each inner array has elements matching the columns returned by the SQL query, in order.

  • objectLines: Returns newline-delimited JSON objects with the HTTP response header Content-Type: text/plain. Newline separation facilitates parsing the entire response set as a stream if you don't have a streaming JSON parser. This format includes a single trailing newline character so you can detect a truncated response.

  • arrayLines: Returns newline-delimited JSON arrays with the HTTP response header Content-Type: text/plain. Newline separation facilitates parsing the entire response set as a stream if you don't have a streaming JSON parser. This format includes a single trailing newline character so you can detect a truncated response.

  • csv: Returns comma-separated values with one row per line. Sent with the HTTP response header Content-Type: text/csv.

    Druid uses double quotes to escape individual field values. For example, a value with a comma returns "A,B". If the field value contains a double quote character, Druid escapes it with a second double quote character. For example, foo"bar becomes foo""bar. This format includes a single trailing newline character so you can detect a truncated response.

sqlTypesHeader
boolean
Default: false

Adds SQL type information in the header. Requires header to be set to true. For compatibility, Druid returns the HTTP header X-Druid-SQL-Header-Included: yes when all of the following conditions are met:

  • The header property is set to true.
  • The version of Druid supports typesHeader and sqlTypesHeader, regardless of whether either property is set.
typesHeader
boolean
Default: false

Adds runtime type information in the header. Requires header to be set to true. Complex types, like sketches, will be reported as COMPLEX<typeName> if a particular complex type name is known for that field, or as COMPLEX if the particular type name is unknown or mixed.

Responses

Request samples

Content type
application/json
{
  • "query": "SELECT \"__time\", \"val\" FROM \"polaris_table\" WHERE \"foo\" = 'bar'",
  • "resultFormat": "array",
  • "header": false,
  • "typesHeader": false,
  • "sqlTypesHeader": false,
  • "context": {
    },
  • "parameters": [
    ]
}

Response samples

Content type
application/json
{
  • "queryId": "string",
  • "state": "ACCEPTED",
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "schema": [
    ],
  • "durationMs": 36000,
  • "result": {
    },
  • "stages": { },
  • "counters": { },
  • "warnings": { }
}

Get results for an async query

Retrieves results for a completed query.

This request doesn’t return results when the async query performs an ingestion job, that is, a query starting with INSERT or REPLACE. To get the status of the ingestion job, see Get job execution status.

Results are separated into pages, so you can use the optional page parameter to refine the results you get. Polaris returns information about the composition of each page and its page number (id).

For information about pages, see Get status of an async query. If you don't specify a page number, the API returns all results sequentially in the same response.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

queryId
required
string (QueryId)
Example: query-94f176eb-3cc8-489e-919e-1135802b8c55

The server-generated ID of the query.

query Parameters
id
string (ResultFormat)
Default: "object"
Enum: "object" "array" "objectLines" "arrayLines" "csv"
Example: id=array

Defines the format in which the results are presented.

page
integer

Fetch results based on page numbers. If not specified, all results are returned sequentially starting from page 0 to N in the same response.

Responses

Response samples

Content type
application/json
[
  • [
    ]
]

Get status of an async query

Retrieves information about the query associated with the given query ID.

The response matches the response from submitting an async query if the query is accepted or running.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

queryId
required
string (QueryId)
Example: query-94f176eb-3cc8-489e-919e-1135802b8c55

The server-generated ID of the query.

query Parameters
detail
boolean
Default: false

Fetch additional details about the query, which includes the information about different stages, counters for each stage, and any warnings.

Responses

Response samples

Content type
application/json
{
  • "queryId": "string",
  • "state": "ACCEPTED",
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "schema": [
    ],
  • "durationMs": 36000,
  • "result": {
    },
  • "stages": { },
  • "counters": { },
  • "warnings": { }
}

Cancel an async query

Cancels a running or accepted async query.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId1)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Identifies the project of the table being queried.

queryId
required
string (QueryId)
Example: query-94f176eb-3cc8-489e-919e-1135802b8c55

The server-generated ID of the query.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "errorCode": "string",
  • "persona": "string",
  • "category": "DEFENSIVE",
  • "errorMessage": "string",
  • "context": { }
}

Tables v1

Manage tables and their schemas.

List all tables in a project

Returns all available tables for a project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

query Parameters
partitioningGranularity
string
Default: "day"
Enum: "second" "minute" "five_minute" "ten_minute" "fifteen_minute" "thirty_minute" "hour" "six_hour" "eight_hour" "day" "week" "month" "quarter" "year" "all"
Example: partitioningGranularity=day

Filters results by the partitioning granularity specified.

segmentCount
integer <int64> >= 0

Filters results by the number of segments specified.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a table

Creates a table.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

Request Body schema: application/json
required

A table to be created.

name
required
string (TableName) [ 1 .. 255 ] characters

The unique, immutable name of the table.

type
required
string (TableType)

The type of table. Once set, you cannot change a table's type. The following table types are supported:

  • detail - A detail table is a standard table that stores each ingested record as a row in the table.
  • aggregate - An aggregate table combines multiple rows based on dimension values and the table's timeResolution, resulting in a condensed data set for improved query performance. See Introduction to data rollup for more details.
version
required
integer <int64> (TableVersion)
Default: 0

The version number of the table. Newly created tables are always initialized at version 0. Do not provide the version number when creating a table. When updating a table, provide the current table version number. If the version number in the request is not the current version, Polaris raises a 409 Conflict error. In that case, retrieve the latest version and retry the request to avoid concurrently conflicting changes.

clusteringColumns
Array of strings (TableClusteringColumns)

Table columns to use for clustering. Polaris sorts table columns within the partition based on their order in this array.

For aggregate tables, only dimensions (not measures) are supported for clustering. If a nonexistent column is specified, Polaris raises a 400 Bad Request error.

For more information, see Clustering.

description
string or null (TableDescription)

The table's description, limited to 1000 characters.

partitioningGranularity
string (TablePartitioningGranularity)
Default: "day"
Enum: "second" "minute" "five_minute" "ten_minute" "fifteen_minute" "thirty_minute" "hour" "six_hour" "eight_hour" "day" "week" "month" "quarter" "year" "all"

The time partitioning of the table. The all granularity groups all data into a single bucket. The week granularity is deprecated. You can't create a new table with the time partitioning set to week. A table sourced by a lookup can only use all partitioning. You can’t change this setting on a table that’s actively used by a lookup.

object (GranularityPayload)

The table's rollup granularity. Determines how to bucket data across the time dimension, such as aggregating data by hour. When set, queryGranularity overrides the rollup granularity in timeResolution.

Array of objects (AggregateTableColumn)
Default: []

The table's schema. The order of the elements determines the order of the columns in the Polaris UI and in SELECT * SQL queries.

schemaMode
string (TableSchemaMode)
Enum: "flexible" "strict"

The table's schema enforcement mode. For more information, see Introduction to tables.

object (TableStoragePolicy)

Policy specifying the time range of data to retain or precache.

  • The retain storage policy determines how long to keep data after which it is deleted.
  • The cached storage policy determines how long to keep data precached. Outside of the cached policy time range, data isn't precached and only resides in lower cost deep storage.

By default, Polaris retains all data and precaches all data. You can’t set a custom storage policy for a table that’s actively used by a lookup. For more information, see Data lifecycle management.

timeResolution
string (TimeResolution)
Default: "millisecond"
Enum: "millisecond" "second" "minute" "fifteen_minute" "thirty_minute" "hour" "day" "week" "month" "quarter" "year" "all"

The table's rollup granularity. See Introduction to data rollup for more details.

You can specify a variable duration or a time zone and origin for a period-type query granularity. When set, queryGranularity overrides the rollup granularity in timeResolution.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "clusteringColumns": [
    ],
  • "description": "Description of example-table",
  • "partitioningGranularity": "day",
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Response samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "availability": "available",
  • "clusteringColumns": [
    ],
  • "createdByUser": {
    },
  • "createdOnTimestamp": "2019-08-24T14:15:22Z",
  • "description": "Description of example-table",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2021-06-06T00:00:00.000Z",
  • "partitioningGranularity": "day",
  • "queryableSchema": [ ],
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "segmentCompactedBytes": 12345678,
  • "segmentCount": 0,
  • "segmentTotalBytes": 12345678,
  • "precachedDataSizeBytes": 12345678,
  • "totalDataSizeBytes": 12345678,
  • "totalRows": 1234,
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Get table details

Returns information for a single table.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

tableName
required
string (TableName) [ 1 .. 255 ] characters
Example: example-table

Name of the table for which to get information.

Responses

Response samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "availability": "available",
  • "clusteringColumns": [
    ],
  • "createdByUser": {
    },
  • "createdOnTimestamp": "2019-08-24T14:15:22Z",
  • "description": "Description of example-table",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2021-06-06T00:00:00.000Z",
  • "partitioningGranularity": "day",
  • "queryableSchema": [ ],
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "segmentCompactedBytes": 12345678,
  • "segmentCount": 0,
  • "segmentTotalBytes": 12345678,
  • "precachedDataSizeBytes": 12345678,
  • "totalDataSizeBytes": 12345678,
  • "totalRows": 1234,
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Update a table

Updates a table.

You can add columns to a table's schema at any point. You can only update or remove columns from a table's schema when the table is empty and has no active ingestion jobs.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

tableName
required
string (TableName) [ 1 .. 255 ] characters
Example: example-table

Name of the table for which to get information.

Request Body schema: application/json
required

The table to be updated.

name
required
string (TableName) [ 1 .. 255 ] characters

The unique, immutable name of the table.

type
required
string (TableType)

The type of table. Once set, you cannot change a table's type. The following table types are supported:

  • detail - A detail table is a standard table that stores each ingested record as a row in the table.
  • aggregate - An aggregate table combines multiple rows based on dimension values and the table's timeResolution, resulting in a condensed data set for improved query performance. See Introduction to data rollup for more details.
version
required
integer <int64> (TableVersion)
Default: 0

The version number of the table. Newly created tables are always initialized at version 0. Do not provide the version number when creating a table. When updating a table, provide the current table version number. If the version number in the request is not the current version, Polaris raises a 409 Conflict error. In that case, retrieve the latest version and retry the request to avoid concurrently conflicting changes.

clusteringColumns
Array of strings (TableClusteringColumns)

Table columns to use for clustering. Polaris sorts table columns within the partition based on their order in this array.

For aggregate tables, only dimensions (not measures) are supported for clustering. If a nonexistent column is specified, Polaris raises a 400 Bad Request error.

For more information, see Clustering.

description
string or null (TableDescription)

The table's description, limited to 1000 characters.

partitioningGranularity
string (TablePartitioningGranularity)
Default: "day"
Enum: "second" "minute" "five_minute" "ten_minute" "fifteen_minute" "thirty_minute" "hour" "six_hour" "eight_hour" "day" "week" "month" "quarter" "year" "all"

The time partitioning of the table. The all granularity groups all data into a single bucket. The week granularity is deprecated. You can't create a new table with the time partitioning set to week. A table sourced by a lookup can only use all partitioning. You can’t change this setting on a table that’s actively used by a lookup.

object (GranularityPayload)

The table's rollup granularity. Determines how to bucket data across the time dimension, such as aggregating data by hour. When set, queryGranularity overrides the rollup granularity in timeResolution.

Array of objects (AggregateTableColumn)
Default: []

The table's schema. The order of the elements determines the order of the columns in the Polaris UI and in SELECT * SQL queries.

schemaMode
string (TableSchemaMode)
Enum: "flexible" "strict"

The table's schema enforcement mode. For more information, see Introduction to tables.

object (TableStoragePolicy)

Policy specifying the time range of data to retain or precache.

  • The retain storage policy determines how long to keep data after which it is deleted.
  • The cached storage policy determines how long to keep data precached. Outside of the cached policy time range, data isn't precached and only resides in lower cost deep storage.

By default, Polaris retains all data and precaches all data. You can’t set a custom storage policy for a table that’s actively used by a lookup. For more information, see Data lifecycle management.

timeResolution
string (TimeResolution)
Default: "millisecond"
Enum: "millisecond" "second" "minute" "fifteen_minute" "thirty_minute" "hour" "day" "week" "month" "quarter" "year" "all"

The table's rollup granularity. See Introduction to data rollup for more details.

You can specify a variable duration or a time zone and origin for a period-type query granularity. When set, queryGranularity overrides the rollup granularity in timeResolution.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "clusteringColumns": [
    ],
  • "description": "Description of example-table",
  • "partitioningGranularity": "day",
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Response samples

Content type
application/json
Example
{
  • "name": "example-table",
  • "type": "aggregate",
  • "version": 0,
  • "availability": "available",
  • "clusteringColumns": [
    ],
  • "createdByUser": {
    },
  • "createdOnTimestamp": "2019-08-24T14:15:22Z",
  • "description": "Description of example-table",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "modifiedByUser": {
    },
  • "modifiedOnTimestamp": "2021-06-06T00:00:00.000Z",
  • "partitioningGranularity": "day",
  • "queryableSchema": [ ],
  • "storagePolicy": {
    },
  • "schemaMode": "flexible",
  • "segmentCompactedBytes": 12345678,
  • "segmentCount": 0,
  • "segmentTotalBytes": 12345678,
  • "precachedDataSizeBytes": 12345678,
  • "totalDataSizeBytes": 12345678,
  • "totalRows": 1234,
  • "queryGranularity": {
    },
  • "schema": [ ],
  • "timeResolution": "millisecond"
}

Get table's unused segments

Returns list of unused segments for the specified table matching query parameters given.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
projectId
required
string (ProjectId)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

The ID of the current project.

tableName
required
string (TableName) [ 1 .. 255 ] characters
Example: example-table

Name of the table for which to get information.

query Parameters
interval
string

Filters results for unused segments by the time interval specified.

lastSegmentId
string (SegmentId)
Example: lastSegmentId=Example_Table_2023-01-01T00:00:00.000Z_2023-01-02T00:00:00.000Z_2023-10-01T00:00:00.000Z

The segmentId to use as a marker from which to search. If sortOrder = ASC or not specified, all segments returned will have a segmentId that is strictly greater than this. If sortOrder = DESC, all segments returned will have a segmentId that is strictly less than this.

limit
integer
Default: 100

The maximum number of segments to return in the response.

sortOrder
string (SortOrder)
Default: "DESC"
Enum: "ASC" "DESC"
Example: sortOrder=ASC

The order with which the resulting segments should be sorted with respect to their segmentId. If not specified, the order of the results is not guaranteed.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Alerts v1

Create and manage alerts and the conditions that trigger them. See Set up alerts for information on managing alerts in the Polaris UI.

List all alerts

Returns all alerts.

Authorizations:
bearerAuthapiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create an alert

Creates an alert.

Authorizations:
bearerAuthapiKeyAuth
Request Body schema: application/json
required
checkFrequency
required
string <duration>

How often Polaris evaluates alert criteria, expressed as an ISO 8601 duration.

required
Array of objects (AlertCondition)

Specify one or more conditions to trigger your alert. If you specify more than one condition, you can set the conditionOperation property to determine whether one or all conditions must be true to trigger the alert.

dataCube
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

owner
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

timeFrame
required
string <duration>

Controls the amount of data Polaris considers when evaluating the alert criteria based upon a time interval, expressed as an ISO 8601 duration.

title
required
string

Alert title to display in the Polaris UI, and in emails and webhooks.

any (AccessList)

Configure user access to the asset.

object (Compare)

A comparison for Pivot Classic data cubes.

conditionOperation
string (ConditionOperation)
Enum: "and" "or"

Select whether one or all conditions must be true to trigger the alert.

dateTimeToStart
string

Date and time to start triggering alerts. The timezone is UTC.

disabled
boolean

Disables the alert. Polaris doesn't evaluate disabled alerts or trigger notifications.

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to notify when the alert triggers.

object (Filter)

Filter to apply to a query.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

instance
string

Optional instance ID to use for the alert configuration.

https://docs.imply.io/latest/managing-data-cubes/#instances
LatestDataStrategy (string) or string (LatestDataStrategyOverride)
any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendEmailToRecipients
boolean

Send email notifications to the alert recipients when the alert triggers.

severity
string (Severity)
Default: "info"
Enum: "info" "warning" "error" "ok"

Severity determines the alert's color and icon in the Polaris UI.

(SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)
type
string (AlertType)
Enum: "overall" "within-split"

Specify overall to evaluate against a measure, and within-split to evaluate against a dimension.

Array of objects (Webhook)

Webhooks to call when the alert is triggered.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ],
  • "exampleQuery": "string"
}

Get alert details

Returns details of a specified alert.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ],
  • "exampleQuery": "string"
}

Update an alert

Updates the details of an alert with a specified ID. You must provide all properties you want to retain in the alert, even if you don't want to update them. Polaris recreates the alert with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Request Body schema: application/json
required

Alert ID.

checkFrequency
required
string <duration>

How often Polaris evaluates alert criteria, expressed as an ISO 8601 duration.

required
Array of objects (AlertCondition)

Specify one or more conditions to trigger your alert. If you specify more than one condition, you can set the conditionOperation property to determine whether one or all conditions must be true to trigger the alert.

dataCube
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

owner
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

timeFrame
required
string <duration>

Controls the amount of data Polaris considers when evaluating the alert criteria based upon a time interval, expressed as an ISO 8601 duration.

title
required
string

Alert title to display in the Polaris UI, and in emails and webhooks.

any (AccessList)

Configure user access to the asset.

object (Compare)

A comparison for Pivot Classic data cubes.

conditionOperation
string (ConditionOperation)
Enum: "and" "or"

Select whether one or all conditions must be true to trigger the alert.

dateTimeToStart
string

Date and time to start triggering alerts. The timezone is UTC.

disabled
boolean

Disables the alert. Polaris doesn't evaluate disabled alerts or trigger notifications.

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to notify when the alert triggers.

object (Filter)

Filter to apply to a query.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

instance
string

Optional instance ID to use for the alert configuration.

https://docs.imply.io/latest/managing-data-cubes/#instances
LatestDataStrategy (string) or string (LatestDataStrategyOverride)
any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendEmailToRecipients
boolean

Send email notifications to the alert recipients when the alert triggers.

severity
string (Severity)
Default: "info"
Enum: "info" "warning" "error" "ok"

Severity determines the alert's color and icon in the Polaris UI.

(SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)
type
string (AlertType)
Enum: "overall" "within-split"

Specify overall to evaluate against a measure, and within-split to evaluate against a dimension.

Array of objects (Webhook)

Webhooks to call when the alert is triggered.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ],
  • "exampleQuery": "string"
}

Update specified alert properties

Updates the specified properties of an alert. Any properties omitted from the request retain their previous values. Polaris creates a new alert if the supplied alert ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Request Body schema: application/merge-patch+json
required

Alert updates

any (AccessList)

Configure user access to the asset.

checkFrequency
string <duration>

How often Polaris evaluates alert criteria, expressed as an ISO 8601 duration.

object (Compare)

A comparison for Pivot Classic data cubes.

conditionOperation
string (ConditionOperation)
Enum: "and" "or"

Select whether one or all conditions must be true to trigger the alert.

Array of objects (AlertCondition)

Specify one or more conditions to trigger your alert. If you specify more than one condition, you can set the conditionOperation property to determine whether one or all conditions must be true to trigger the alert.

dataCube
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

dateTimeToStart
string

Date and time to start triggering alerts. The timezone is UTC.

disabled
boolean

Disables the alert. Polaris doesn't evaluate disabled alerts or trigger notifications.

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to notify when the alert triggers.

object (Filter)

Filter to apply to a query.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

instance
string

Optional instance ID to use for the alert configuration.

https://docs.imply.io/latest/managing-data-cubes/#instances
LatestDataStrategy (string) or string (LatestDataStrategyOverride)
owner
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendEmailToRecipients
boolean

Send email notifications to the alert recipients when the alert triggers.

severity
string (Severity)
Default: "info"
Enum: "info" "warning" "error" "ok"

Severity determines the alert's color and icon in the Polaris UI.

(SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)
timeFrame
string <duration>

Controls the amount of data Polaris considers when evaluating the alert criteria based upon a time interval, expressed as an ISO 8601 duration.

title
string

Alert title to display in the Polaris UI, and in emails and webhooks.

type
string (AlertType)
Enum: "overall" "within-split"

Specify overall to evaluate against a measure, and within-split to evaluate against a dimension.

Array of objects (Webhook)

Webhooks to call when the alert is triggered.

property name*
additional property
any

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ]
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "owner": "wikipedia-1234",
  • "title": "My alert",
  • "dataCube": "wikipedia-1234",
  • "dateTimeToStart": "2025-02-01T10:30:00.000Z",
  • "instance": "string",
  • "type": "overall",
  • "checkFrequency": "PT5M",
  • "timeFrame": "P1D",
  • "compare": {
    },
  • "filter": {
    },
  • "splits": "string",
  • "conditionOperation": "and",
  • "conditions": [
    ],
  • "severity": "info",
  • "readAccess": {
    },
  • "recipients": {
    },
  • "admins": {
    },
  • "webhooks": [
    ],
  • "disabled": true,
  • "sendEmailToRecipients": true,
  • "latestDataStrategyOverride": "query",
  • "externalEmails": [
    ],
  • "exampleQuery": "string"
}

Delete an alert

Deletes an alert.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Get alert evaluations

Returns all evaluations for an alert.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Get alert evaluation details

Returns information for a single alert evaluation.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
evaluationId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Evaluation ID.

id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Alert ID.

Responses

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "alertId": "wikipedia-1234",
  • "alert": {
    },
  • "triggerDate": "2019-08-24T14:15:22Z",
  • "maxDate": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "summaries": [
    ],
  • "errors": [
    ],
  • "queries": [
    ]
}

Collections v1

Create, edit, and delete Polaris collections. See Collections and favorites for information on managing collections in the Polaris UI.

List all collections

Returns all collections in a specified project.

Authorizations:
bearerAuth
path Parameters
projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a collection

Creates a collection in a specified project.

Authorizations:
bearerAuth
path Parameters
projectId
required
string

Project ID.

Request Body schema: application/json
required
name
required
string (CollectionName)

Name of the collection.

description
string (CollectionDescription)

Description of the collection.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Get a collection

Returns a single collection in a specified project.

Authorizations:
bearerAuth
path Parameters
id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Update specified collection properties

Updates a collection name and/or description.

Authorizations:
bearerAuth
path Parameters
id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Request Body schema: application/merge-patch+json
required

The collection updates

description
string (CollectionDescription)

Description of the collection.

name
string (CollectionName)

Name of the collection.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Delete a collection

Deletes a single collection in a specified project.

Authorizations:
bearerAuth
path Parameters
id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Add assets to a collection

Adds specified assets to a collection.

Authorizations:
bearerAuth
path Parameters
id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Request Body schema: application/json
required

Assets to add to the collection.

required
Array of objects (CollectionAsset)

Responses

Request samples

Content type
application/json
{
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "description": "string",
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Remove an asset from a collection Deprecated

Deprecated. To remove a specified asset from a collection, use this endpoint.

Authorizations:
bearerAuth
path Parameters
assetId
required
string (CollectionAssetId)

Collection asset ID.

id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Remove an asset from a collection

Removes a specified asset from a collection.

Authorizations:
bearerAuth
path Parameters
assetId
required
string (CollectionAssetId)

Collection asset ID.

assetType
required
any (CollectionAssetType)
Enum: "dataCube" "dashboard" "alert" "report" "embedding" "table" "connection" "file"

Collection asset type.

id
required
integer (CollectionId)

Collection ID.

projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

List favorites

Returns all favorites for the authenticated user.

Authorizations:
bearerAuth
path Parameters
projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Add assets to favorites

Adds specified assets to the authenticated user's favorites.

Authorizations:
bearerAuth
path Parameters
projectId
required
string

Project ID.

Request Body schema: application/json
required

Assets to add to favorites.

required
Array of objects (CollectionAsset)

Responses

Request samples

Content type
application/json
{
  • "values": [
    ]
}

Response samples

Content type
application/json
{
  • "assets": [
    ],
  • "createdBy": {
    },
  • "createdAt": "2021-06-06T00:00:00.000Z",
  • "updatedBy": {
    },
  • "updatedAt": "2021-06-06T00:00:00.000Z"
}

Remove an asset from favorites Deprecated

Deprecated. To remove a specified asset from the authenticated user's favorites, use this endpoint.

Authorizations:
bearerAuth
path Parameters
assetId
required
string (CollectionAssetId)

Collection asset ID.

projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Remove an asset from favorites

Removes a specified asset from the authenticated user's favorites.

Authorizations:
bearerAuth
path Parameters
assetId
required
string (CollectionAssetId)

Collection asset ID.

assetType
required
any (CollectionAssetType)
Enum: "dataCube" "dashboard" "alert" "report" "embedding" "table" "connection" "file"

Collection asset type.

projectId
required
string

Project ID.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Customizations v1

Set and manage customized logos, colors, and visualization colors in the Imply Polaris UI for your organization. See Customize Polaris for information on managing customizations in the Polaris UI.

Get application name

Returns the application name of the organization.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "appName": "Example Company",
  • "lastModifiedBy": {
    },
  • "lastUpdateTimestamp": "2023-03-10T15:35:59.000Z"
}

Update application name

Updates the application name of the organization.

Authorizations:
bearerAuth
Request Body schema: application/json
required
appName
string

Application name.

Responses

Request samples

Content type
application/json
{
  • "appName": "Example Company"
}

Response samples

Content type
application/json
{
  • "appName": "Example Company",
  • "lastModifiedBy": {
    },
  • "lastUpdateTimestamp": "2023-03-10T15:35:59.000Z"
}

Delete application name

Deletes the customized application name of the organization. The application name is reset to the default - Imply.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Get logos

Returns the customized logos of the organization.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{}

Delete all logos

Deletes all customized logos for the organization. Logos are reset to the Polaris defaults.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Get theme

Returns the visual theme applied to the organization, including color palettes for the Polaris UI and visualizations.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "appPalette": {
    },
  • "visPalette": {
    },
  • "lastModifiedBy": {
    },
  • "lastUpdateTimestamp": "2023-03-10T15:35:59.000Z"
}

Update entire theme

Updates the visual theme for the organization, including color palettes for the Polaris UI and visualizations. Any properties omitted from the request reset to the default values.

Authorizations:
bearerAuth
Request Body schema: application/json
required

New theme details

object or null (AppColorPalette)

Color palette for the Polaris UI. Use the 6-character hex format for all colors.

object or null (VisualizationColorPalette)

Color palette for visualizations. Use the 6-character hex format for all colors.

Responses

Request samples

Content type
application/json
{
  • "appPalette": {
    },
  • "visPalette": {
    }
}

Response samples

Content type
application/json
{
  • "appPalette": {
    },
  • "visPalette": {
    },
  • "lastModifiedBy": {
    },
  • "lastUpdateTimestamp": "2023-03-10T15:35:59.000Z"
}

Update specified theme properties

Updates the visual theme for the organization, including color palettes for the Polaris UI and visualizations. Any properties omitted from the request retain their previous values.

Authorizations:
bearerAuth
Request Body schema: application/merge-patch+json
required

Theme updates

object or null (AppColorPalette)

Color palette for the Polaris UI. Use the 6-character hex format for all colors.

object or null (VisualizationColorPalette)

Color palette for visualizations. Use the 6-character hex format for all colors.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "appPalette": {
    },
  • "visPalette": {
    }
}

Response samples

Content type
application/json
{
  • "appPalette": {
    },
  • "visPalette": {
    },
  • "lastModifiedBy": {
    },
  • "lastUpdateTimestamp": "2023-03-10T15:35:59.000Z"
}

Delete theme

Deletes the visual theme applied to the organization, including custom color palettes for the Polaris UI and visualizations. Colors are reset to the Polaris defaults.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string",
  • "target": "string",
  • "details": [
    ],
  • "innererror": {
    }
}

Dashboards v1

Create and manage alerts and their pages and tiles. See Dashboards overview for information on managing dashboards in the Polaris UI.

List all dashboards

Returns all dashboards.

Authorizations:
bearerAuthapiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a dashboard

Creates a dashboard.

Authorizations:
bearerAuthapiKeyAuth
Request Body schema: application/json
required
title
required
string

Dashboard title to display in the Polaris UI.

object (DashboardCompare)

Comparison that can be applied to a dashboard.

Array of objects (DashboardFilter)

Default filters to apply to the dashboard.

defaultMeasures
Array of strings (Identifier) [ items [ 1 .. 255 ] characters ]

IDs of default measures to apply to the dashboard.

defaultRefreshRate
string <duration>

Default refresh rate for the dashboard, expressed as an ISO 8601 Duration.

description
string

Dashboard description.

enforceTimeFilter
boolean
Default: false

Ensure that every query is filtered on the primary time dimension.

filterQueryDefaultDuration
string <duration>
Default: "P1D"

Default time period used for filter queries, expressed as an ISO 8601 Duration.

filterTile
string (ShowHide)
Enum: "show" "hide"
hasGlobalCompare
boolean
Default: false

Enable global comparisons.

hasGlobalMeasures
boolean
Default: false

Enable global measures.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

minAutoRefreshRate
string <duration>

The rate under which this dashboard won't refresh, expressed as an ISO 8601 Duration.

any (AccessList)

Configure user access to the asset.

Array of objects

Array of dashboard pages.

pagesColorSummary
string (ShowHide)
Enum: "show" "hide"
pagesTile
string (ShowHide)
Enum: "show" "hide"
object or null (AppColorPalette)

Color palette for the Polaris UI. Use the 6-character hex format for all colors.

any (AccessList)

Configure user access to the asset.

type
string (DashboardType)
Default: "dashboard2"
Enum: "classic" "dashboard2"

Dashboard type - always "dashboard2".

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "type": "classic",
  • "title": "string",
  • "description": "string",
  • "palette": {
    },
  • "readAccess": {
    },
  • "modifyAccess": {
    },
  • "pages": [
    ],
  • "defaultFilters": [
    ],
  • "enforceTimeFilter": false,
  • "filterTile": "show",
  • "pagesTile": "show",
  • "pagesColorSummary": "show",
  • "hasGlobalCompare": false,
  • "defaultCompare": {
    },
  • "hasGlobalMeasures": false,
  • "defaultMeasures": [
    ],
  • "filterQueryDefaultDuration": "PT5M",
  • "defaultRefreshRate": "PT5M",
  • "minAutoRefreshRate": "PT5M"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "type": "classic",
  • "title": "string",
  • "description": "string",
  • "palette": {
    },
  • "readAccess": {
    },
  • "modifyAccess": {
    },
  • "pages": [
    ],
  • "defaultFilters": [
    ],
  • "enforceTimeFilter": false,
  • "filterTile": "show",
  • "pagesTile": "show",
  • "pagesColorSummary": "show",
  • "hasGlobalCompare": false,
  • "defaultCompare": {
    },
  • "hasGlobalMeasures": false,
  • "defaultMeasures": [
    ],
  • "filterQueryDefaultDuration": "PT5M",
  • "defaultRefreshRate": "PT5M",
  • "minAutoRefreshRate": "PT5M"
}

Get dashboard details

Returns details of a specified dashboard.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "type": "classic",
  • "title": "string",
  • "description": "string",
  • "palette": {
    },
  • "readAccess": {
    },
  • "modifyAccess": {
    },
  • "pages": [
    ],
  • "defaultFilters": [
    ],
  • "enforceTimeFilter": false,
  • "filterTile": "show",
  • "pagesTile": "show",
  • "pagesColorSummary": "show",
  • "hasGlobalCompare": false,
  • "defaultCompare": {
    },
  • "hasGlobalMeasures": false,
  • "defaultMeasures": [
    ],
  • "filterQueryDefaultDuration": "PT5M",
  • "defaultRefreshRate": "PT5M",
  • "minAutoRefreshRate": "PT5M"
}

Update a dashboard

Updates the details of a dashboard with a specified ID. You must provide all properties you want to retain in the dashboard, even if you don't want to update them. Polaris recreates the dashboard with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

Request Body schema: application/json
required

Dashboard to update.

title
required
string

Dashboard title to display in the Polaris UI.

object (DashboardCompare)

Comparison that can be applied to a dashboard.

Array of objects (DashboardFilter)

Default filters to apply to the dashboard.

defaultMeasures
Array of strings (Identifier) [ items [ 1 .. 255 ] characters ]

IDs of default measures to apply to the dashboard.

defaultRefreshRate
string <duration>

Default refresh rate for the dashboard, expressed as an ISO 8601 Duration.

description
string

Dashboard description.

enforceTimeFilter
boolean
Default: false

Ensure that every query is filtered on the primary time dimension.

filterQueryDefaultDuration
string <duration>
Default: "P1D"

Default time period used for filter queries, expressed as an ISO 8601 Duration.

filterTile
string (ShowHide)
Enum: "show" "hide"
hasGlobalCompare
boolean
Default: false

Enable global comparisons.

hasGlobalMeasures
boolean
Default: false

Enable global measures.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

minAutoRefreshRate
string <duration>

The rate under which this dashboard won't refresh, expressed as an ISO 8601 Duration.

any (AccessList)

Configure user access to the asset.

Array of objects

Array of dashboard pages.

pagesColorSummary
string (ShowHide)
Enum: "show" "hide"
pagesTile
string (ShowHide)
Enum: "show" "hide"
object or null (AppColorPalette)

Color palette for the Polaris UI. Use the 6-character hex format for all colors.

any (AccessList)

Configure user access to the asset.

type
string (DashboardType)
Default: "dashboard2"
Enum: "classic" "dashboard2"

Dashboard type - always "dashboard2".

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "type": "classic",
  • "title": "string",
  • "description": "string",
  • "palette": {
    },
  • "readAccess": {
    },
  • "modifyAccess": {
    },
  • "pages": [
    ],
  • "defaultFilters": [
    ],
  • "enforceTimeFilter": false,
  • "filterTile": "show",
  • "pagesTile": "show",
  • "pagesColorSummary": "show",
  • "hasGlobalCompare": false,
  • "defaultCompare": {
    },
  • "hasGlobalMeasures": false,
  • "defaultMeasures": [
    ],
  • "filterQueryDefaultDuration": "PT5M",
  • "defaultRefreshRate": "PT5M",
  • "minAutoRefreshRate": "PT5M"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "type": "classic",
  • "title": "string",
  • "description": "string",
  • "palette": {
    },
  • "readAccess": {
    },
  • "modifyAccess": {
    },
  • "pages": [
    ],
  • "defaultFilters": [
    ],
  • "enforceTimeFilter": false,
  • "filterTile": "show",
  • "pagesTile": "show",
  • "pagesColorSummary": "show",
  • "hasGlobalCompare": false,
  • "defaultCompare": {
    },
  • "hasGlobalMeasures": false,
  • "defaultMeasures": [
    ],
  • "filterQueryDefaultDuration": "PT5M",
  • "defaultRefreshRate": "PT5M",
  • "minAutoRefreshRate": "PT5M"
}

Update specified dashboard properties

Updates the specified properties of a dashboard. Any properties omitted from the request retain their previous values. Polaris creates a new dashboard if the supplied dashboard ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

Request Body schema: application/merge-patch+json
required

Dashboard updates

object (DashboardCompare)

Comparison that can be applied to a dashboard.

Array of objects (DashboardFilter)

Default filters to apply to the dashboard.

defaultMeasures
Array of strings (Identifier) [ items [ 1 .. 255 ] characters ]

IDs of default measures to apply to the dashboard.

defaultRefreshRate
string <duration>

Default refresh rate for the dashboard, expressed as an ISO 8601 Duration.

description
string

Dashboard description.

enforceTimeFilter
boolean
Default: false

Ensure that every query is filtered on the primary time dimension.

filterQueryDefaultDuration
string <duration>
Default: "P1D"

Default time period used for filter queries, expressed as an ISO 8601 Duration.

filterTile
string (ShowHide)
Enum: "show" "hide"
hasGlobalCompare
boolean
Default: false

Enable global comparisons.

hasGlobalMeasures
boolean
Default: false

Enable global measures.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

minAutoRefreshRate
string <duration>

The rate under which this dashboard won't refresh, expressed as an ISO 8601 Duration.

any (AccessList)

Configure user access to the asset.

Array of objects

Array of dashboard pages.

pagesColorSummary
string (ShowHide)
Enum: "show" "hide"
pagesTile
string (ShowHide)
Enum: "show" "hide"
object or null (AppColorPalette)

Color palette for the Polaris UI. Use the 6-character hex format for all colors.

any (AccessList)

Configure user access to the asset.

title
string

Dashboard title to display in the Polaris UI.

type
string (DashboardType)
Default: "dashboard2"
Enum: "classic" "dashboard2"

Dashboard type - always "dashboard2".

property name*
additional property
any

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "type": "classic",
  • "title": "string",
  • "description": "string",
  • "palette": {
    },
  • "readAccess": {
    },
  • "modifyAccess": {
    },
  • "pages": [
    ],
  • "defaultFilters": [
    ],
  • "enforceTimeFilter": false,
  • "filterTile": "show",
  • "pagesTile": "show",
  • "pagesColorSummary": "show",
  • "hasGlobalCompare": false,
  • "defaultCompare": {
    },
  • "hasGlobalMeasures": false,
  • "defaultMeasures": [
    ],
  • "filterQueryDefaultDuration": "PT5M",
  • "defaultRefreshRate": "PT5M",
  • "minAutoRefreshRate": "PT5M"
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "type": "classic",
  • "title": "string",
  • "description": "string",
  • "palette": {
    },
  • "readAccess": {
    },
  • "modifyAccess": {
    },
  • "pages": [
    ],
  • "defaultFilters": [
    ],
  • "enforceTimeFilter": false,
  • "filterTile": "show",
  • "pagesTile": "show",
  • "pagesColorSummary": "show",
  • "hasGlobalCompare": false,
  • "defaultCompare": {
    },
  • "hasGlobalMeasures": false,
  • "defaultMeasures": [
    ],
  • "filterQueryDefaultDuration": "PT5M",
  • "defaultRefreshRate": "PT5M",
  • "minAutoRefreshRate": "PT5M"
}

Delete a dashboard

Deletes a dashboard.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Get dashboard data cubes

Returns the data cubes associated with a dashboard via its tiles.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Get dashboard pages

Returns all pages for a dashboard.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a dashboard page

Creates a dashboard page

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

Request Body schema: application/json
required
id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

label
string

Page label to display in the Polaris UI.

Array of objects

Dashboard page tiles.

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "label": "string",
  • "tiles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "label": "string",
  • "tiles": [
    ]
}

Get page details

Returns information for a single dashboard page.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

Responses

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "label": "string",
  • "tiles": [
    ]
}

Update a page

Updates the details of a dashboard page with a specified ID. You must provide all properties you want to retain in the page even if you don't want to update them. Polaris recreates the page with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

Request Body schema: application/json
required

Page to update.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

label
string

Page label to display in the Polaris UI.

Array of objects

Dashboard page tiles.

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "label": "string",
  • "tiles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "label": "string",
  • "tiles": [
    ]
}

Update specified page properties

Updates the specified properties of a page. Polaris creates a new page if the supplied page ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

Request Body schema: application/merge-patch+json
required

Page updates

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

label
string

Page label to display in the Polaris UI.

Array of objects

Dashboard page tiles.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "label": "string",
  • "tiles": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "label": "string",
  • "tiles": [
    ]
}

Delete a page

Deletes a page.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Get dashboard page tiles

Returns all tiles for a dashboard page.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a dashboard page tile

Creates a new tile for a dashboard page.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

Request Body schema: application/json
required
type
required
string (TileType)
Enum: "blank" "visualization" "markdown"

Tile type. blank tiles are empty. visualization tiles display a data cube visualization. markdown tiles display a block of text using Markdown formatting.

canExpand
boolean
Default: true

Tile can be expanded into a full data cube view.

content
string

Markdown content to display in the tile. Only applicable if "type" is set to "markdown". Polaris renders markdown content using Markdown formatting.

description
string

Tile description to display in info popovers in the dashboard UI.

object

Visualization definition for data cubes. This is not applicable to Polaris.

object (ExploreEssence)

State of a visualization in the Explore View

object (FacetEssence)

State of a visualization in the Pivot 2 view

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

infoHidden
boolean
Default: false

Hide the tile info popover.

legendSide
string (LegendSide)
Enum: "none" "right" "bottom"

Side of the tile to display the legend.

object (TilePosition)

Position of a tile within a dashboard page.

title
string

Tile title to display in the dashboard UI. If not set, defaults to an auto-generated title based on the displayed dimensions and measures.

titleHidden
boolean
Default: false

Hide the tile title.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "type": "blank",
  • "title": "string",
  • "description": "string",
  • "position": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "titleHidden": false,
  • "infoHidden": false,
  • "canExpand": true,
  • "content": "string",
  • "legendSide": "none"
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "type": "blank",
  • "title": "string",
  • "description": "string",
  • "position": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "titleHidden": false,
  • "infoHidden": false,
  • "canExpand": true,
  • "content": "string",
  • "legendSide": "none"
}

Get tile details

Returns the definition for a single dashboard tile.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

tileId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Tile ID.

Responses

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "type": "blank",
  • "title": "string",
  • "description": "string",
  • "position": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "titleHidden": false,
  • "infoHidden": false,
  • "canExpand": true,
  • "content": "string",
  • "legendSide": "none"
}

Update a tile

Updates the details of a dashboard page tile with a specified ID. You must provide all properties you want to retain in the tile even if you don't want to update them. Polaris recreates the tile with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

tileId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Tile ID.

Request Body schema: application/json
required

The tile to update.

type
required
string (TileType)
Enum: "blank" "visualization" "markdown"

Tile type. blank tiles are empty. visualization tiles display a data cube visualization. markdown tiles display a block of text using Markdown formatting.

canExpand
boolean
Default: true

Tile can be expanded into a full data cube view.

content
string

Markdown content to display in the tile. Only applicable if "type" is set to "markdown". Polaris renders markdown content using Markdown formatting.

description
string

Tile description to display in info popovers in the dashboard UI.

object

Visualization definition for data cubes. This is not applicable to Polaris.

object (ExploreEssence)

State of a visualization in the Explore View

object (FacetEssence)

State of a visualization in the Pivot 2 view

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

infoHidden
boolean
Default: false

Hide the tile info popover.

legendSide
string (LegendSide)
Enum: "none" "right" "bottom"

Side of the tile to display the legend.

object (TilePosition)

Position of a tile within a dashboard page.

title
string

Tile title to display in the dashboard UI. If not set, defaults to an auto-generated title based on the displayed dimensions and measures.

titleHidden
boolean
Default: false

Hide the tile title.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "type": "blank",
  • "title": "string",
  • "description": "string",
  • "position": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "titleHidden": false,
  • "infoHidden": false,
  • "canExpand": true,
  • "content": "string",
  • "legendSide": "none"
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "type": "blank",
  • "title": "string",
  • "description": "string",
  • "position": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "titleHidden": false,
  • "infoHidden": false,
  • "canExpand": true,
  • "content": "string",
  • "legendSide": "none"
}

Update specified tile properties

Updates the specified properties of a dashboard page tile. Polaris creates a new tile if the supplied tile ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

tileId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Tile ID.

Request Body schema: application/merge-patch+json
required

Tile updates

canExpand
boolean
Default: true

Tile can be expanded into a full data cube view.

content
string

Markdown content to display in the tile. Only applicable if "type" is set to "markdown". Polaris renders markdown content using Markdown formatting.

description
string

Tile description to display in info popovers in the dashboard UI.

object

Visualization definition for data cubes. This is not applicable to Polaris.

object (ExploreEssence)

State of a visualization in the Explore View

object (FacetEssence)

State of a visualization in the Pivot 2 view

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

infoHidden
boolean
Default: false

Hide the tile info popover.

legendSide
string (LegendSide)
Enum: "none" "right" "bottom"

Side of the tile to display the legend.

object (TilePosition)

Position of a tile within a dashboard page.

title
string

Tile title to display in the dashboard UI. If not set, defaults to an auto-generated title based on the displayed dimensions and measures.

titleHidden
boolean
Default: false

Hide the tile title.

type
string (TileType)
Enum: "blank" "visualization" "markdown"

Tile type. blank tiles are empty. visualization tiles display a data cube visualization. markdown tiles display a block of text using Markdown formatting.

property name*
additional property
any

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "type": "blank",
  • "title": "string",
  • "description": "string",
  • "position": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "titleHidden": false,
  • "infoHidden": false,
  • "canExpand": true,
  • "content": "string",
  • "legendSide": "none"
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "type": "blank",
  • "title": "string",
  • "description": "string",
  • "position": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "titleHidden": false,
  • "infoHidden": false,
  • "canExpand": true,
  • "content": "string",
  • "legendSide": "none"
}

Delete a tile

Deletes a dashboard page tile.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dashboard ID.

pageId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Page ID.

tileId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Tile ID.

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Data cubes v1

Create and manage data cubes and their dimensions and measures. See Manage data cubes for information on managing data cubes in the Polaris UI.

List all data cubes

Returns all data cubes.

Authorizations:
bearerAuthapiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a data cube

Creates a data cube.

Authorizations:
bearerAuthapiKeyAuth
Request Body schema: application/json
required
queryMode
required
string (QueryMode)
Enum: "sql" "plywood"

Data cube query mode.

required
object (DataCubeSource)

Data cube source.

title
required
string

Data cube title.

allowFilterCombine
boolean

Determines the behaviour when a user is a member of two or more user groups with access filters applied. If true, Polaris combines the filters with the OR operator. If false, the user can't view any data in the data cube.

Array of objects (Attribute)

Column metadata for the associated data source.

Array of objects (FacetCompare)

Customized comparisons for the data cube.

defaultDuration
string <duration>

Time period to display when a user first opens the data cube, expressed as an ISO 8601 duration.

object (FacetCompare)

Comparison for data cubes.

Array of (SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)

Default dimensions to split on.

object (Filter)

Filter to apply to a query.

object (HavingFilter)

HAVING filter to apply to a measure.

defaultParameters
string

The default parameters to populate an Explore visualization.

defaultPinnedDimensions
Array of strings

IDs of the dimensions to pin by default in visualizations.

defaultRefreshRate
string <duration>

The default refresh rate for the data cube, expressed as an ISO 8601 Duration.

defaultSelectedMeasures
Array of strings

IDs of the measures to show by default in visualizations.

defaultTimezone
string

Time zone to select when a user first opens the data cube, expressed as an Olsen Timezone.

defaultVisualization
string

Name of the default visualization to use when initially viewing the data cube.

description
string

Data cube description.

Array of objects (DimensionPayload)

The dimensions of the data cube.

any (AccessList)

Configure user access to the asset.

enforceTimeFilter
boolean

Ensures that every query is filtered on the primary time dimension. You can enable this setting if time unbounded queries are likely to be slow due to the volume of data.

filterToken
string

Only allow users with the given filter token to access this data cube.

formulaeVisibility
string (Visibility)
Enum: "show" "hide"

Whether a field should be shown or hidden.

object

Defines access filters for a user group.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

object (DataCubeInstanceList)

Data cube instances.

latestDataStrategy
string (LatestDataStrategy)
Enum: "query" "query-floored-P1D" "predefined"

Determines how Polaris calculates the latest data time for the data cube. By default, Polaris queries the data source for the latest time stamp on ingested data. You can set this property to always use the current time, which may be more appropriate for streaming data.

latestTimeFilterGranularity
string <duration>

When using a relative time filter, Polaris uses this level of granularity to align the filter boundaries when querying the underlying table, expressed as an ISO 8601 Duration. For an aggregate table, set to the same granularity used during ingestion or leave unset for Polaris to infer an appropriate value from the data. For a detail table, leave unset.

Array of objects (MeasurePayload)

Array of data cube measures.

minAlertFrequency
string <duration>

Minimum allowable frequency for alerts associated with this data cube, expressed as an ISO 8601 Duration.

minAlertTimeFrame
string <duration>

Minimum allowable time frame for alerts associated with this data cube, expressed as an ISO 8601 Duration.

minAutoRefreshRate
string <duration>

Minimum auto refresh rate for the data cube, expressed as an ISO 8601 Duration.

any (AccessList)

Configure user access to the asset.

object (DataCubeOptions)

Data cube options.

object or null (AppColorPalette)

Color palette for the Polaris UI. Use the 6-character hex format for all colors.

queryCaching
string
Enum: "allow" "disable"

Allow caching on queries made to this data cube. Caching can greatly speed up exploration but can also cause results to be a little out of date especially in realtime rolled up datasets.

any (AccessList)

Configure user access to the asset.

requireGroupFilters
boolean

Enable this property to use access filters. When enabled, users who aren't assigned an access filter can't perform queries.

any (AccessList)

Configure user access to the asset.

rollup
boolean

Whether the associated table has rollup enabled.

specialTimeDimension
string

Time dimension Polaris uses for all time-related calculations for the data cube, including comparisons, filters, alerts, and reports. Polarise uses this to check the freshness of data and apply time filters.

subsetFormula
string

Row level filter to apply to the data cube. This filter is never shown in the cube view and effectively constrains the data cube to only the events that match this filter.

object

Defines access filters for a Polaris API key.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "queryMode": "sql",
  • "source": {
    },
  • "palette": {
    },
  • "minAutoRefreshRate": "PT5M",
  • "latestTimeFilterGranularity": "PT5M",
  • "subsetFormula": "string",
  • "filterToken": "string",
  • "rollup": true,
  • "options": {
    },
  • "readAccess": {
    },
  • "restrictedEditAccess": {
    },
  • "modifyAccess": {
    },
  • "downloadAccess": {
    },
  • "attributes": [
    ],
  • "dimensions": [
    ],
  • "measures": [
    ],
  • "instances": {
    },
  • "specialTimeDimension": "string",
  • "enforceTimeFilter": true,
  • "defaultFilter": {
    },
  • "defaultTimezone": "string",
  • "defaultDuration": "PT5M",
  • "defaultSelectedMeasures": [
    ],
  • "defaultPinnedDimensions": [
    ],
  • "defaultRefreshRate": "string",
  • "defaultVisualization": "string",
  • "defaultHavingFilter": {
    },
  • "latestDataStrategy": "query",
  • "queryCaching": "allow",
  • "formulaeVisibility": "show",
  • "minAlertFrequency": "PT5M",
  • "minAlertTimeFrame": "PT5M",
  • "defaultParameters": "string",
  • "defaultFacetSplits": [
    ],
  • "defaultFacetCompare": {
    },
  • "customFacetCompares": [
    ],
  • "requireGroupFilters": true,
  • "allowFilterCombine": true,
  • "groupFilters": {
    },
  • "userFilters": {
    }
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "queryMode": "sql",
  • "source": {
    },
  • "palette": {
    },
  • "minAutoRefreshRate": "PT5M",
  • "latestTimeFilterGranularity": "PT5M",
  • "subsetFormula": "string",
  • "filterToken": "string",
  • "rollup": true,
  • "options": {
    },
  • "readAccess": {
    },
  • "restrictedEditAccess": {
    },
  • "modifyAccess": {
    },
  • "downloadAccess": {
    },
  • "attributes": [
    ],
  • "dimensions": [
    ],
  • "measures": [
    ],
  • "instances": {
    },
  • "specialTimeDimension": "string",
  • "enforceTimeFilter": true,
  • "defaultFilter": {
    },
  • "defaultTimezone": "string",
  • "defaultDuration": "PT5M",
  • "defaultSelectedMeasures": [
    ],
  • "defaultPinnedDimensions": [
    ],
  • "defaultRefreshRate": "string",
  • "defaultVisualization": "string",
  • "defaultHavingFilter": {
    },
  • "latestDataStrategy": "query",
  • "queryCaching": "allow",
  • "formulaeVisibility": "show",
  • "minAlertFrequency": "PT5M",
  • "minAlertTimeFrame": "PT5M",
  • "defaultParameters": "string",
  • "defaultFacetSplits": [
    ],
  • "defaultFacetCompare": {
    },
  • "customFacetCompares": [
    ],
  • "requireGroupFilters": true,
  • "allowFilterCombine": true,
  • "groupFilters": {
    },
  • "userFilters": {
    }
}

Get data cube details

Returns details of a specified data cube.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "queryMode": "sql",
  • "source": {
    },
  • "palette": {
    },
  • "minAutoRefreshRate": "PT5M",
  • "latestTimeFilterGranularity": "PT5M",
  • "subsetFormula": "string",
  • "filterToken": "string",
  • "rollup": true,
  • "options": {
    },
  • "readAccess": {
    },
  • "restrictedEditAccess": {
    },
  • "modifyAccess": {
    },
  • "downloadAccess": {
    },
  • "attributes": [
    ],
  • "dimensions": [
    ],
  • "measures": [
    ],
  • "instances": {
    },
  • "specialTimeDimension": "string",
  • "enforceTimeFilter": true,
  • "defaultFilter": {
    },
  • "defaultTimezone": "string",
  • "defaultDuration": "PT5M",
  • "defaultSelectedMeasures": [
    ],
  • "defaultPinnedDimensions": [
    ],
  • "defaultRefreshRate": "string",
  • "defaultVisualization": "string",
  • "defaultHavingFilter": {
    },
  • "latestDataStrategy": "query",
  • "queryCaching": "allow",
  • "formulaeVisibility": "show",
  • "minAlertFrequency": "PT5M",
  • "minAlertTimeFrame": "PT5M",
  • "defaultParameters": "string",
  • "defaultFacetSplits": [
    ],
  • "defaultFacetCompare": {
    },
  • "customFacetCompares": [
    ],
  • "requireGroupFilters": true,
  • "allowFilterCombine": true,
  • "groupFilters": {
    },
  • "userFilters": {
    }
}

Update a data cube

Updates the details of a data cube with a specified ID. You must provide all properties you want to retain in the data cube, even if you don't want to update them. Polaris recreates the data cube with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Request Body schema: application/json
required

The data cube to be updated

queryMode
required
string (QueryMode)
Enum: "sql" "plywood"

Data cube query mode.

required
object (DataCubeSource)

Data cube source.

title
required
string

Data cube title.

allowFilterCombine
boolean

Determines the behaviour when a user is a member of two or more user groups with access filters applied. If true, Polaris combines the filters with the OR operator. If false, the user can't view any data in the data cube.

Array of objects (Attribute)

Column metadata for the associated data source.

Array of objects (FacetCompare)

Customized comparisons for the data cube.

defaultDuration
string <duration>

Time period to display when a user first opens the data cube, expressed as an ISO 8601 duration.

object (FacetCompare)

Comparison for data cubes.

Array of (SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)

Default dimensions to split on.

object (Filter)

Filter to apply to a query.

object (HavingFilter)

HAVING filter to apply to a measure.

defaultParameters
string

The default parameters to populate an Explore visualization.

defaultPinnedDimensions
Array of strings

IDs of the dimensions to pin by default in visualizations.

defaultRefreshRate
string <duration>

The default refresh rate for the data cube, expressed as an ISO 8601 Duration.

defaultSelectedMeasures
Array of strings

IDs of the measures to show by default in visualizations.

defaultTimezone
string

Time zone to select when a user first opens the data cube, expressed as an Olsen Timezone.

defaultVisualization
string

Name of the default visualization to use when initially viewing the data cube.

description
string

Data cube description.

Array of objects (DimensionPayload)

The dimensions of the data cube.

any (AccessList)

Configure user access to the asset.

enforceTimeFilter
boolean

Ensures that every query is filtered on the primary time dimension. You can enable this setting if time unbounded queries are likely to be slow due to the volume of data.

filterToken
string

Only allow users with the given filter token to access this data cube.

formulaeVisibility
string (Visibility)
Enum: "show" "hide"

Whether a field should be shown or hidden.

object

Defines access filters for a user group.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

object (DataCubeInstanceList)

Data cube instances.

latestDataStrategy
string (LatestDataStrategy)
Enum: "query" "query-floored-P1D" "predefined"

Determines how Polaris calculates the latest data time for the data cube. By default, Polaris queries the data source for the latest time stamp on ingested data. You can set this property to always use the current time, which may be more appropriate for streaming data.

latestTimeFilterGranularity
string <duration>

When using a relative time filter, Polaris uses this level of granularity to align the filter boundaries when querying the underlying table, expressed as an ISO 8601 Duration. For an aggregate table, set to the same granularity used during ingestion or leave unset for Polaris to infer an appropriate value from the data. For a detail table, leave unset.

Array of objects (MeasurePayload)

Array of data cube measures.

minAlertFrequency
string <duration>

Minimum allowable frequency for alerts associated with this data cube, expressed as an ISO 8601 Duration.

minAlertTimeFrame
string <duration>

Minimum allowable time frame for alerts associated with this data cube, expressed as an ISO 8601 Duration.

minAutoRefreshRate
string <duration>

Minimum auto refresh rate for the data cube, expressed as an ISO 8601 Duration.

any (AccessList)

Configure user access to the asset.

object (DataCubeOptions)

Data cube options.

object or null (AppColorPalette)

Color palette for the Polaris UI. Use the 6-character hex format for all colors.

queryCaching
string
Enum: "allow" "disable"

Allow caching on queries made to this data cube. Caching can greatly speed up exploration but can also cause results to be a little out of date especially in realtime rolled up datasets.

any (AccessList)

Configure user access to the asset.

requireGroupFilters
boolean

Enable this property to use access filters. When enabled, users who aren't assigned an access filter can't perform queries.

any (AccessList)

Configure user access to the asset.

rollup
boolean

Whether the associated table has rollup enabled.

specialTimeDimension
string

Time dimension Polaris uses for all time-related calculations for the data cube, including comparisons, filters, alerts, and reports. Polarise uses this to check the freshness of data and apply time filters.

subsetFormula
string

Row level filter to apply to the data cube. This filter is never shown in the cube view and effectively constrains the data cube to only the events that match this filter.

object

Defines access filters for a Polaris API key.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "queryMode": "sql",
  • "source": {
    },
  • "palette": {
    },
  • "minAutoRefreshRate": "PT5M",
  • "latestTimeFilterGranularity": "PT5M",
  • "subsetFormula": "string",
  • "filterToken": "string",
  • "rollup": true,
  • "options": {
    },
  • "readAccess": {
    },
  • "restrictedEditAccess": {
    },
  • "modifyAccess": {
    },
  • "downloadAccess": {
    },
  • "attributes": [
    ],
  • "dimensions": [
    ],
  • "measures": [
    ],
  • "instances": {
    },
  • "specialTimeDimension": "string",
  • "enforceTimeFilter": true,
  • "defaultFilter": {
    },
  • "defaultTimezone": "string",
  • "defaultDuration": "PT5M",
  • "defaultSelectedMeasures": [
    ],
  • "defaultPinnedDimensions": [
    ],
  • "defaultRefreshRate": "string",
  • "defaultVisualization": "string",
  • "defaultHavingFilter": {
    },
  • "latestDataStrategy": "query",
  • "queryCaching": "allow",
  • "formulaeVisibility": "show",
  • "minAlertFrequency": "PT5M",
  • "minAlertTimeFrame": "PT5M",
  • "defaultParameters": "string",
  • "defaultFacetSplits": [
    ],
  • "defaultFacetCompare": {
    },
  • "customFacetCompares": [
    ],
  • "requireGroupFilters": true,
  • "allowFilterCombine": true,
  • "groupFilters": {
    },
  • "userFilters": {
    }
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "queryMode": "sql",
  • "source": {
    },
  • "palette": {
    },
  • "minAutoRefreshRate": "PT5M",
  • "latestTimeFilterGranularity": "PT5M",
  • "subsetFormula": "string",
  • "filterToken": "string",
  • "rollup": true,
  • "options": {
    },
  • "readAccess": {
    },
  • "restrictedEditAccess": {
    },
  • "modifyAccess": {
    },
  • "downloadAccess": {
    },
  • "attributes": [
    ],
  • "dimensions": [
    ],
  • "measures": [
    ],
  • "instances": {
    },
  • "specialTimeDimension": "string",
  • "enforceTimeFilter": true,
  • "defaultFilter": {
    },
  • "defaultTimezone": "string",
  • "defaultDuration": "PT5M",
  • "defaultSelectedMeasures": [
    ],
  • "defaultPinnedDimensions": [
    ],
  • "defaultRefreshRate": "string",
  • "defaultVisualization": "string",
  • "defaultHavingFilter": {
    },
  • "latestDataStrategy": "query",
  • "queryCaching": "allow",
  • "formulaeVisibility": "show",
  • "minAlertFrequency": "PT5M",
  • "minAlertTimeFrame": "PT5M",
  • "defaultParameters": "string",
  • "defaultFacetSplits": [
    ],
  • "defaultFacetCompare": {
    },
  • "customFacetCompares": [
    ],
  • "requireGroupFilters": true,
  • "allowFilterCombine": true,
  • "groupFilters": {
    },
  • "userFilters": {
    }
}

Update specified data cube properties

Updates the specified properties of a data cube. Any properties omitted from the request retain their previous values. Polaris creates a new data cube if the supplied data cube ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Request Body schema: application/merge-patch+json
required

Data cube updates

allowFilterCombine
boolean

Determines the behaviour when a user is a member of two or more user groups with access filters applied. If true, Polaris combines the filters with the OR operator. If false, the user can't view any data in the data cube.

Array of objects (Attribute)

Column metadata for the associated data source.

Array of objects (FacetCompare)

Customized comparisons for the data cube.

defaultDuration
string <duration>

Time period to display when a user first opens the data cube, expressed as an ISO 8601 duration.

object (FacetCompare)

Comparison for data cubes.

Array of (SplitCombine (SplitCombine (string) or SplitCombineFull (object))) or (Array of SplitCombine (strings or SplitCombineFull (object))) (Splits)

Default dimensions to split on.

object (Filter)

Filter to apply to a query.

object (HavingFilter)

HAVING filter to apply to a measure.

defaultParameters
string

The default parameters to populate an Explore visualization.

defaultPinnedDimensions
Array of strings

IDs of the dimensions to pin by default in visualizations.

defaultRefreshRate
string <duration>

The default refresh rate for the data cube, expressed as an ISO 8601 Duration.

defaultSelectedMeasures
Array of strings

IDs of the measures to show by default in visualizations.

defaultTimezone
string

Time zone to select when a user first opens the data cube, expressed as an Olsen Timezone.

defaultVisualization
string

Name of the default visualization to use when initially viewing the data cube.

description
string

Data cube description.

Array of objects (DimensionPayload)

The dimensions of the data cube.

any (AccessList)

Configure user access to the asset.

enforceTimeFilter
boolean

Ensures that every query is filtered on the primary time dimension. You can enable this setting if time unbounded queries are likely to be slow due to the volume of data.

filterToken
string

Only allow users with the given filter token to access this data cube.

formulaeVisibility
string (Visibility)
Enum: "show" "hide"

Whether a field should be shown or hidden.

object

Defines access filters for a user group.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

object (DataCubeInstanceList)

Data cube instances.

latestDataStrategy
string (LatestDataStrategy)
Enum: "query" "query-floored-P1D" "predefined"

Determines how Polaris calculates the latest data time for the data cube. By default, Polaris queries the data source for the latest time stamp on ingested data. You can set this property to always use the current time, which may be more appropriate for streaming data.

latestTimeFilterGranularity
string <duration>

When using a relative time filter, Polaris uses this level of granularity to align the filter boundaries when querying the underlying table, expressed as an ISO 8601 Duration. For an aggregate table, set to the same granularity used during ingestion or leave unset for Polaris to infer an appropriate value from the data. For a detail table, leave unset.

Array of objects (MeasurePayload)

Array of data cube measures.

minAlertFrequency
string <duration>

Minimum allowable frequency for alerts associated with this data cube, expressed as an ISO 8601 Duration.

minAlertTimeFrame
string <duration>

Minimum allowable time frame for alerts associated with this data cube, expressed as an ISO 8601 Duration.

minAutoRefreshRate
string <duration>

Minimum auto refresh rate for the data cube, expressed as an ISO 8601 Duration.

any (AccessList)

Configure user access to the asset.

object (DataCubeOptions)

Data cube options.

object or null (AppColorPalette)

Color palette for the Polaris UI. Use the 6-character hex format for all colors.

queryCaching
string
Enum: "allow" "disable"

Allow caching on queries made to this data cube. Caching can greatly speed up exploration but can also cause results to be a little out of date especially in realtime rolled up datasets.

queryMode
string (QueryMode)
Enum: "sql" "plywood"

Data cube query mode.

any (AccessList)

Configure user access to the asset.

requireGroupFilters
boolean

Enable this property to use access filters. When enabled, users who aren't assigned an access filter can't perform queries.

any (AccessList)

Configure user access to the asset.

rollup
boolean

Whether the associated table has rollup enabled.

object (DataCubeSource)

Data cube source.

specialTimeDimension
string

Time dimension Polaris uses for all time-related calculations for the data cube, including comparisons, filters, alerts, and reports. Polarise uses this to check the freshness of data and apply time filters.

subsetFormula
string

Row level filter to apply to the data cube. This filter is never shown in the cube view and effectively constrains the data cube to only the events that match this filter.

title
string

Data cube title.

object

Defines access filters for a Polaris API key.

property name*
additional property
any

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "queryMode": "sql",
  • "source": {
    },
  • "palette": {
    },
  • "minAutoRefreshRate": "PT5M",
  • "latestTimeFilterGranularity": "PT5M",
  • "subsetFormula": "string",
  • "filterToken": "string",
  • "rollup": true,
  • "options": {
    },
  • "readAccess": {
    },
  • "restrictedEditAccess": {
    },
  • "modifyAccess": {
    },
  • "downloadAccess": {
    },
  • "attributes": [
    ],
  • "dimensions": [
    ],
  • "measures": [
    ],
  • "instances": {
    },
  • "specialTimeDimension": "string",
  • "enforceTimeFilter": true,
  • "defaultFilter": {
    },
  • "defaultTimezone": "string",
  • "defaultDuration": "PT5M",
  • "defaultSelectedMeasures": [
    ],
  • "defaultPinnedDimensions": [
    ],
  • "defaultRefreshRate": "string",
  • "defaultVisualization": "string",
  • "defaultHavingFilter": {
    },
  • "latestDataStrategy": "query",
  • "queryCaching": "allow",
  • "formulaeVisibility": "show",
  • "minAlertFrequency": "PT5M",
  • "minAlertTimeFrame": "PT5M",
  • "defaultParameters": "string",
  • "defaultFacetSplits": [
    ],
  • "defaultFacetCompare": {
    },
  • "customFacetCompares": [
    ],
  • "requireGroupFilters": true,
  • "allowFilterCombine": true,
  • "groupFilters": {
    },
  • "userFilters": {
    }
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "queryMode": "sql",
  • "source": {
    },
  • "palette": {
    },
  • "minAutoRefreshRate": "PT5M",
  • "latestTimeFilterGranularity": "PT5M",
  • "subsetFormula": "string",
  • "filterToken": "string",
  • "rollup": true,
  • "options": {
    },
  • "readAccess": {
    },
  • "restrictedEditAccess": {
    },
  • "modifyAccess": {
    },
  • "downloadAccess": {
    },
  • "attributes": [
    ],
  • "dimensions": [
    ],
  • "measures": [
    ],
  • "instances": {
    },
  • "specialTimeDimension": "string",
  • "enforceTimeFilter": true,
  • "defaultFilter": {
    },
  • "defaultTimezone": "string",
  • "defaultDuration": "PT5M",
  • "defaultSelectedMeasures": [
    ],
  • "defaultPinnedDimensions": [
    ],
  • "defaultRefreshRate": "string",
  • "defaultVisualization": "string",
  • "defaultHavingFilter": {
    },
  • "latestDataStrategy": "query",
  • "queryCaching": "allow",
  • "formulaeVisibility": "show",
  • "minAlertFrequency": "PT5M",
  • "minAlertTimeFrame": "PT5M",
  • "defaultParameters": "string",
  • "defaultFacetSplits": [
    ],
  • "defaultFacetCompare": {
    },
  • "customFacetCompares": [
    ],
  • "requireGroupFilters": true,
  • "allowFilterCombine": true,
  • "groupFilters": {
    },
  • "userFilters": {
    }
}

Delete a data cube

Deletes a data cube.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Get data cube dimensions

Returns all dimensions for a data cube.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a data cube dimension

Creates a dimension for a data cube.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

query Parameters
order
integer

Array order of the new dimension

Request Body schema: application/json
required
bucketingStrategy
string (BucketingStrategy)
Enum: "defaultBucket" "defaultNoBucket" "neverBucket" "alwaysBucket"

The bucketing strategy for a dimension.

description
string

Dimension description.

format
string

Date/time format to use for TIME dimensions. See MomentJS docs for more information.

https://momentjs.com/docs/?/displaying/format/#/displaying/
formula
string

SQL expression for the dimension. Refer to the associated Polaris table by its alias "t".

geo
boolean

Indicates that this is a geographic dimension. You must also provide a valid geoEncoding and set the dimension type.

geoEncoding
string (GeoEncodingType)
Enum: "ISO 3166-1 Alpha-2" "ISO 3166-1 Alpha-3" "ISO 3166-2" "UN M49" "Geohash" "lng-coordinate" "lat-coordinate"

The geo encoding type for a dimension. Geo dimensions require specific data types to be set depending on the geo encoding type. For lat-coordinate or lng-coordinate dimensions, set the type to number. For all other geo encodings, set the type to string.

https://docs.imply.io/latest/dimensions#geographic-dimensions
Array of strings or numbers or objects

Preset bucketing granularities for time and numeric dimensions.

group
string

Dimensions with the same value for this property are grouped together in the dimensions panel.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

ipPrefix
boolean

Store the dimension as a complex data type representing an IP prefix. Requires the IP dimension type.

title
string

Dimension title.

type
string (DimensionType)
Enum: "TIME" "STRING" "SET/STRING" "NUMBER" "BOOLEAN" "IP" "TIME_SERIES"

Specific data type for a dimension. For IP Prefix dimensions, use the IP data type and set ipPrefix: true on the dimension.

url
string

URL transformation for string dimensions. Polaris interpolates the provided string and replaces %s with the dimension value.

https://docs.imply.io/latest/dimensions#url-dimensions
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "formula": "COALESCE(LOOKUP(t.\"Country\", 'store_sales_country_to_iso31661'), t.\"Country\")",
  • "type": "TIME",
  • "geo": true,
  • "geoEncoding": "ISO 3166-1 Alpha-2",
  • "ipPrefix": true,
  • "format": "string",
  • "url": "https://en.wikipedia.org/wiki/%s",
  • "granularities": [
    ],
  • "bucketingStrategy": "defaultBucket"
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "formula": "COALESCE(LOOKUP(t.\"Country\", 'store_sales_country_to_iso31661'), t.\"Country\")",
  • "type": "TIME",
  • "geo": true,
  • "geoEncoding": "ISO 3166-1 Alpha-2",
  • "ipPrefix": true,
  • "format": "string",
  • "url": "https://en.wikipedia.org/wiki/%s",
  • "granularities": [
    ],
  • "bucketingStrategy": "defaultBucket"
}

Get dimension details

Returns information for a single data cube dimension.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
dimensionId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dimension identifier

id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Responses

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "formula": "COALESCE(LOOKUP(t.\"Country\", 'store_sales_country_to_iso31661'), t.\"Country\")",
  • "type": "TIME",
  • "geo": true,
  • "geoEncoding": "ISO 3166-1 Alpha-2",
  • "ipPrefix": true,
  • "format": "string",
  • "url": "https://en.wikipedia.org/wiki/%s",
  • "granularities": [
    ],
  • "bucketingStrategy": "defaultBucket"
}

Update a dimension

Updates the details of a dimension with a specified ID. You must provide all properties you want to retain in the dimension even if you don't want to update them. Polaris recreates the dimension with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
dimensionId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dimension identifier

id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Request Body schema: application/json
required

The dimension to be updated

bucketingStrategy
string (BucketingStrategy)
Enum: "defaultBucket" "defaultNoBucket" "neverBucket" "alwaysBucket"

The bucketing strategy for a dimension.

description
string

Dimension description.

format
string

Date/time format to use for TIME dimensions. See MomentJS docs for more information.

https://momentjs.com/docs/?/displaying/format/#/displaying/
formula
string

SQL expression for the dimension. Refer to the associated Polaris table by its alias "t".

geo
boolean

Indicates that this is a geographic dimension. You must also provide a valid geoEncoding and set the dimension type.

geoEncoding
string (GeoEncodingType)
Enum: "ISO 3166-1 Alpha-2" "ISO 3166-1 Alpha-3" "ISO 3166-2" "UN M49" "Geohash" "lng-coordinate" "lat-coordinate"

The geo encoding type for a dimension. Geo dimensions require specific data types to be set depending on the geo encoding type. For lat-coordinate or lng-coordinate dimensions, set the type to number. For all other geo encodings, set the type to string.

https://docs.imply.io/latest/dimensions#geographic-dimensions
Array of strings or numbers or objects

Preset bucketing granularities for time and numeric dimensions.

group
string

Dimensions with the same value for this property are grouped together in the dimensions panel.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

ipPrefix
boolean

Store the dimension as a complex data type representing an IP prefix. Requires the IP dimension type.

title
string

Dimension title.

type
string (DimensionType)
Enum: "TIME" "STRING" "SET/STRING" "NUMBER" "BOOLEAN" "IP" "TIME_SERIES"

Specific data type for a dimension. For IP Prefix dimensions, use the IP data type and set ipPrefix: true on the dimension.

url
string

URL transformation for string dimensions. Polaris interpolates the provided string and replaces %s with the dimension value.

https://docs.imply.io/latest/dimensions#url-dimensions
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "formula": "COALESCE(LOOKUP(t.\"Country\", 'store_sales_country_to_iso31661'), t.\"Country\")",
  • "type": "TIME",
  • "geo": true,
  • "geoEncoding": "ISO 3166-1 Alpha-2",
  • "ipPrefix": true,
  • "format": "string",
  • "url": "https://en.wikipedia.org/wiki/%s",
  • "granularities": [
    ],
  • "bucketingStrategy": "defaultBucket"
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "formula": "COALESCE(LOOKUP(t.\"Country\", 'store_sales_country_to_iso31661'), t.\"Country\")",
  • "type": "TIME",
  • "geo": true,
  • "geoEncoding": "ISO 3166-1 Alpha-2",
  • "ipPrefix": true,
  • "format": "string",
  • "url": "https://en.wikipedia.org/wiki/%s",
  • "granularities": [
    ],
  • "bucketingStrategy": "defaultBucket"
}

Update specified dimension properties

Updates the specified properties of a dimension. Any properties omitted from the request retain their previous values. Polaris creates a new dimension if the supplied dimension ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
dimensionId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dimension identifier

id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Request Body schema: application/merge-patch+json
required

Dimension updates

bucketingStrategy
string (BucketingStrategy)
Enum: "defaultBucket" "defaultNoBucket" "neverBucket" "alwaysBucket"

The bucketing strategy for a dimension.

description
string

Dimension description.

format
string

Date/time format to use for TIME dimensions. See MomentJS docs for more information.

https://momentjs.com/docs/?/displaying/format/#/displaying/
formula
string

SQL expression for the dimension. Refer to the associated Polaris table by its alias "t".

geo
boolean

Indicates that this is a geographic dimension. You must also provide a valid geoEncoding and set the dimension type.

geoEncoding
string (GeoEncodingType)
Enum: "ISO 3166-1 Alpha-2" "ISO 3166-1 Alpha-3" "ISO 3166-2" "UN M49" "Geohash" "lng-coordinate" "lat-coordinate"

The geo encoding type for a dimension. Geo dimensions require specific data types to be set depending on the geo encoding type. For lat-coordinate or lng-coordinate dimensions, set the type to number. For all other geo encodings, set the type to string.

https://docs.imply.io/latest/dimensions#geographic-dimensions
Array of strings or numbers or objects

Preset bucketing granularities for time and numeric dimensions.

group
string

Dimensions with the same value for this property are grouped together in the dimensions panel.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

ipPrefix
boolean

Store the dimension as a complex data type representing an IP prefix. Requires the IP dimension type.

title
string

Dimension title.

type
string (DimensionType)
Enum: "TIME" "STRING" "SET/STRING" "NUMBER" "BOOLEAN" "IP" "TIME_SERIES"

Specific data type for a dimension. For IP Prefix dimensions, use the IP data type and set ipPrefix: true on the dimension.

url
string

URL transformation for string dimensions. Polaris interpolates the provided string and replaces %s with the dimension value.

https://docs.imply.io/latest/dimensions#url-dimensions
property name*
additional property
any

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "formula": "COALESCE(LOOKUP(t.\"Country\", 'store_sales_country_to_iso31661'), t.\"Country\")",
  • "type": "TIME",
  • "geo": true,
  • "geoEncoding": "ISO 3166-1 Alpha-2",
  • "ipPrefix": true,
  • "format": "string",
  • "url": "https://en.wikipedia.org/wiki/%s",
  • "granularities": [
    ],
  • "bucketingStrategy": "defaultBucket"
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "formula": "COALESCE(LOOKUP(t.\"Country\", 'store_sales_country_to_iso31661'), t.\"Country\")",
  • "type": "TIME",
  • "geo": true,
  • "geoEncoding": "ISO 3166-1 Alpha-2",
  • "ipPrefix": true,
  • "format": "string",
  • "url": "https://en.wikipedia.org/wiki/%s",
  • "granularities": [
    ],
  • "bucketingStrategy": "defaultBucket"
}

Delete a dimension

Deletes a dimension.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
dimensionId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dimension identifier

id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Get data cube measures

Returns all measures for a data cube.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a data cube measure

Creates a measure for a data cube.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

query Parameters
order
integer

Array order of the new measure

Request Body schema: application/json
required
object (ComparisonColors)

Determines the display coloring for increased and decreased values.

description
string

Measure description.

formula
string

SQL expression for the measure. Refer to tables with the alias "t".

group
string

Groups measures with the same group value together in the measures panel.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

missingValueFill
string (MissingValueFill)
Enum: "zero" "none" "previous" "interpolate"

Specifies how to fill empty values for a measure on continuous visualizations:

  • zero: (default) Fill missing data with zeros. This is most suitable if the measure represents an additive quantity.
  • none: Leave missing data empty. This is suitable when missing values indicate that the data is not collected.
  • previous: Fill missing data with last value seen. This is suitable for sensor type data.
  • interpolate: Interpolate the missing data between the seen value. This is suitable for sensor type data.
object (NumberStyle)

Measure formatting.

scaleBehavior
string (ScaleBehavior)
Enum: "pin-zero" "unpinned"

Determines how the scale behaves in "continuous" visualizations (such as the line chart):

  • pin-zero: Always include 0 for reference.
  • unpinned: Do not force 0 into the scale.
title
string

Measure title.

transform
string (MeasureTransform)
Enum: "none" "percent-of-parent" "percent-of-root"

You can transform a measure to be displayed as Percent of parent segment or as Percent of total instead of the default measure display.

units
string

Added as a suffix.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "units": "string",
  • "formula": "SUM(t.\"revenue\") FILTER (WHERE t.\"country\" = 'United States')",
  • "transform": "none",
  • "numberStyle": {
    },
  • "missingValueFill": "zero",
  • "scaleBehavior": "pin-zero",
  • "comparisonColors": {
    }
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "units": "string",
  • "formula": "SUM(t.\"revenue\") FILTER (WHERE t.\"country\" = 'United States')",
  • "transform": "none",
  • "numberStyle": {
    },
  • "missingValueFill": "zero",
  • "scaleBehavior": "pin-zero",
  • "comparisonColors": {
    }
}

Get measure details

Returns information for a single data cube measure.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

measureId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dimension identifier

Responses

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "units": "string",
  • "formula": "SUM(t.\"revenue\") FILTER (WHERE t.\"country\" = 'United States')",
  • "transform": "none",
  • "numberStyle": {
    },
  • "missingValueFill": "zero",
  • "scaleBehavior": "pin-zero",
  • "comparisonColors": {
    }
}

Update a measure

Updates the details of a measure with a specified ID. You must provide all properties you want to retain in the measure, even if you don't want to update them. Polaris recreates the measure with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

measureId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dimension identifier

Request Body schema: application/json
required

Measure to be update.

object (ComparisonColors)

Determines the display coloring for increased and decreased values.

description
string

Measure description.

formula
string

SQL expression for the measure. Refer to tables with the alias "t".

group
string

Groups measures with the same group value together in the measures panel.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

missingValueFill
string (MissingValueFill)
Enum: "zero" "none" "previous" "interpolate"

Specifies how to fill empty values for a measure on continuous visualizations:

  • zero: (default) Fill missing data with zeros. This is most suitable if the measure represents an additive quantity.
  • none: Leave missing data empty. This is suitable when missing values indicate that the data is not collected.
  • previous: Fill missing data with last value seen. This is suitable for sensor type data.
  • interpolate: Interpolate the missing data between the seen value. This is suitable for sensor type data.
object (NumberStyle)

Measure formatting.

scaleBehavior
string (ScaleBehavior)
Enum: "pin-zero" "unpinned"

Determines how the scale behaves in "continuous" visualizations (such as the line chart):

  • pin-zero: Always include 0 for reference.
  • unpinned: Do not force 0 into the scale.
title
string

Measure title.

transform
string (MeasureTransform)
Enum: "none" "percent-of-parent" "percent-of-root"

You can transform a measure to be displayed as Percent of parent segment or as Percent of total instead of the default measure display.

units
string

Added as a suffix.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "units": "string",
  • "formula": "SUM(t.\"revenue\") FILTER (WHERE t.\"country\" = 'United States')",
  • "transform": "none",
  • "numberStyle": {
    },
  • "missingValueFill": "zero",
  • "scaleBehavior": "pin-zero",
  • "comparisonColors": {
    }
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "units": "string",
  • "formula": "SUM(t.\"revenue\") FILTER (WHERE t.\"country\" = 'United States')",
  • "transform": "none",
  • "numberStyle": {
    },
  • "missingValueFill": "zero",
  • "scaleBehavior": "pin-zero",
  • "comparisonColors": {
    }
}

Update specified measure properties

Updates the specified properties of a measure. Any properties omitted from the request retain their previous values. Polaris creates a new measure if the supplied measure ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

measureId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dimension identifier

Request Body schema: application/merge-patch+json
required

Measure updates

object (ComparisonColors)

Determines the display coloring for increased and decreased values.

description
string

Measure description.

formula
string

SQL expression for the measure. Refer to tables with the alias "t".

group
string

Groups measures with the same group value together in the measures panel.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

missingValueFill
string (MissingValueFill)
Enum: "zero" "none" "previous" "interpolate"

Specifies how to fill empty values for a measure on continuous visualizations:

  • zero: (default) Fill missing data with zeros. This is most suitable if the measure represents an additive quantity.
  • none: Leave missing data empty. This is suitable when missing values indicate that the data is not collected.
  • previous: Fill missing data with last value seen. This is suitable for sensor type data.
  • interpolate: Interpolate the missing data between the seen value. This is suitable for sensor type data.
object (NumberStyle)

Measure formatting.

scaleBehavior
string (ScaleBehavior)
Enum: "pin-zero" "unpinned"

Determines how the scale behaves in "continuous" visualizations (such as the line chart):

  • pin-zero: Always include 0 for reference.
  • unpinned: Do not force 0 into the scale.
title
string

Measure title.

transform
string (MeasureTransform)
Enum: "none" "percent-of-parent" "percent-of-root"

You can transform a measure to be displayed as Percent of parent segment or as Percent of total instead of the default measure display.

units
string

Added as a suffix.

property name*
additional property
any

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "units": "string",
  • "formula": "SUM(t.\"revenue\") FILTER (WHERE t.\"country\" = 'United States')",
  • "transform": "none",
  • "numberStyle": {
    },
  • "missingValueFill": "zero",
  • "scaleBehavior": "pin-zero",
  • "comparisonColors": {
    }
}

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "title": "string",
  • "description": "string",
  • "group": "string",
  • "units": "string",
  • "formula": "SUM(t.\"revenue\") FILTER (WHERE t.\"country\" = 'United States')",
  • "transform": "none",
  • "numberStyle": {
    },
  • "missingValueFill": "zero",
  • "scaleBehavior": "pin-zero",
  • "comparisonColors": {
    }
}

Delete a measure

Deletes a measure.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Data cube identifier

measureId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Dimension identifier

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Create a secret key for an embedding link

Creates an ECDSA private key that is required to access the embedding link.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Embedding link ID.

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Delete a secret key for an embedding link

Deletes the ECDSA public key associated with an embedding link. After deletion the link will function as a public link.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Embedding link ID.

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Embedding v1 (deprecated)

The Embedding v1 API has been deprecated in favor of the Embedding links API. For information about how to adopt the new API, see Migration guide for deprecated APIs.

Create a private key for an embedding link Deprecated

Creates an ECDSA private key that is required to access the embedding link.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
linkId
required
string

Embedding link ID.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "embeddingSecret": "string"
}

Delete a public key for an embedding link Deprecated

Deletes the ECDSA public key associated with an embedding link. After deletion the link will function as a public link.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
linkId
required
string

Embedding link ID.

Responses

Response samples

Content type
application/json
{ }

Reports v1

Create and manage reports and their evaluations. See Set up reports for information on managing reports in the Polaris UI.

List all reports

Returns all reports.

Authorizations:
bearerAuthapiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a report

Creates a report.

Authorizations:
bearerAuthapiKeyAuth
Request Body schema: application/json
required
creationDate
required
string <date-time>

Timestamp when the report was created.

owner
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

addTotalRowToFile
boolean
Default: false

Adds a line to the attachment that shows an overall total. You can't apply this option to JSON format attachments.

any (AccessList)

Configure user access to the asset.

object (Delivery)

Delivery configuration for a report.

description
string

Report description to display in the Polaris UI, and in emails and webhooks.

disabled
boolean

Disables the report. Polaris doesn't evaluate disabled reports or send notifications.

number or string
Default: 500

Maximum number of rows to include in the report attachment. Defaults to 500.

enforceDecimalFormatting
boolean
Default: false

Formats numeric values in the report attachment as decimals.

object

Visualization definition for classic data cubes. This is not applicable to Polaris.

object (ExploreEssence)

State of a visualization in the Explore View

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to receive report notications.

object (FacetEssence)

State of a visualization in the Pivot 2 view

fileFormat
string
Default: "csv"
Enum: "csv" "tsv" "xlsx" "json"

Format of the report data attachment. Defaults to CSV.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

preferredView
string
Default: "pivot1"
Enum: "pivot1" "pivot2" "explore"

View to use when viewing the report in Polaris. Defaults to pivot1. When supplying a facetEssence, set to pivot2. When supplying an exploreEssence, set to explore.

any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendDataFile
boolean
Default: true

Sends the report data as an attachment.

sendEmail
boolean

Sends email notifications to the report recipients when the report is generated.

object (TimeFrame)
timezone
string
Default: "Etc/UTC"

Timezone to use when evaluating report criteria. Defaults to UTC.

title
string

Report title to display in the Polaris UI, and in emails and webhooks.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "owner": "wikipedia-1234",
  • "title": "My report",
  • "description": "string",
  • "disabled": true,
  • "delivery": {
    },
  • "preferredView": "pivot1",
  • "timeFrame": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "admins": {
    },
  • "readAccess": {
    },
  • "recipients": {
    },
  • "externalEmails": [
    ],
  • "timezone": "America/Los_Angeles",
  • "sendDataFile": true,
  • "addTotalRowToFile": false,
  • "fileFormat": "csv",
  • "downloadLimit": 500,
  • "enforceDecimalFormatting": false,
  • "sendEmail": true
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "owner": "wikipedia-1234",
  • "title": "My report",
  • "description": "string",
  • "disabled": true,
  • "delivery": {
    },
  • "preferredView": "pivot1",
  • "timeFrame": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "admins": {
    },
  • "readAccess": {
    },
  • "recipients": {
    },
  • "externalEmails": [
    ],
  • "timezone": "America/Los_Angeles",
  • "sendDataFile": true,
  • "addTotalRowToFile": false,
  • "fileFormat": "csv",
  • "downloadLimit": 500,
  • "enforceDecimalFormatting": false,
  • "sendEmail": true
}

Get report details

Returns details of a specified report.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Report ID.

Responses

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "owner": "wikipedia-1234",
  • "title": "My report",
  • "description": "string",
  • "disabled": true,
  • "delivery": {
    },
  • "preferredView": "pivot1",
  • "timeFrame": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "admins": {
    },
  • "readAccess": {
    },
  • "recipients": {
    },
  • "externalEmails": [
    ],
  • "timezone": "America/Los_Angeles",
  • "sendDataFile": true,
  • "addTotalRowToFile": false,
  • "fileFormat": "csv",
  • "downloadLimit": 500,
  • "enforceDecimalFormatting": false,
  • "sendEmail": true
}

Update a report

Updates the details of a report with a specified ID. You must provide all properties you want to retain in the report, even if you don't want to update them. Polaris recreates the report with the details you specify in the request.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Report ID.

Request Body schema: application/json
required

Report ID.

creationDate
required
string <date-time>

Timestamp when the report was created.

owner
required
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

addTotalRowToFile
boolean
Default: false

Adds a line to the attachment that shows an overall total. You can't apply this option to JSON format attachments.

any (AccessList)

Configure user access to the asset.

object (Delivery)

Delivery configuration for a report.

description
string

Report description to display in the Polaris UI, and in emails and webhooks.

disabled
boolean

Disables the report. Polaris doesn't evaluate disabled reports or send notifications.

number or string
Default: 500

Maximum number of rows to include in the report attachment. Defaults to 500.

enforceDecimalFormatting
boolean
Default: false

Formats numeric values in the report attachment as decimals.

object

Visualization definition for classic data cubes. This is not applicable to Polaris.

object (ExploreEssence)

State of a visualization in the Explore View

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to receive report notications.

object (FacetEssence)

State of a visualization in the Pivot 2 view

fileFormat
string
Default: "csv"
Enum: "csv" "tsv" "xlsx" "json"

Format of the report data attachment. Defaults to CSV.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

preferredView
string
Default: "pivot1"
Enum: "pivot1" "pivot2" "explore"

View to use when viewing the report in Polaris. Defaults to pivot1. When supplying a facetEssence, set to pivot2. When supplying an exploreEssence, set to explore.

any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendDataFile
boolean
Default: true

Sends the report data as an attachment.

sendEmail
boolean

Sends email notifications to the report recipients when the report is generated.

object (TimeFrame)
timezone
string
Default: "Etc/UTC"

Timezone to use when evaluating report criteria. Defaults to UTC.

title
string

Report title to display in the Polaris UI, and in emails and webhooks.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "owner": "wikipedia-1234",
  • "title": "My report",
  • "description": "string",
  • "disabled": true,
  • "delivery": {
    },
  • "preferredView": "pivot1",
  • "timeFrame": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "admins": {
    },
  • "readAccess": {
    },
  • "recipients": {
    },
  • "externalEmails": [
    ],
  • "timezone": "America/Los_Angeles",
  • "sendDataFile": true,
  • "addTotalRowToFile": false,
  • "fileFormat": "csv",
  • "downloadLimit": 500,
  • "enforceDecimalFormatting": false,
  • "sendEmail": true
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "owner": "wikipedia-1234",
  • "title": "My report",
  • "description": "string",
  • "disabled": true,
  • "delivery": {
    },
  • "preferredView": "pivot1",
  • "timeFrame": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "admins": {
    },
  • "readAccess": {
    },
  • "recipients": {
    },
  • "externalEmails": [
    ],
  • "timezone": "America/Los_Angeles",
  • "sendDataFile": true,
  • "addTotalRowToFile": false,
  • "fileFormat": "csv",
  • "downloadLimit": 500,
  • "enforceDecimalFormatting": false,
  • "sendEmail": true
}

Update specified report properties

Updates the specified properties of a report. Any properties omitted from the request retain their previous values. Polaris creates a new report if the supplied report ID doesn't exist.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Report ID.

Request Body schema: application/merge-patch+json
required

Report updates

addTotalRowToFile
boolean
Default: false

Adds a line to the attachment that shows an overall total. You can't apply this option to JSON format attachments.

any (AccessList)

Configure user access to the asset.

creationDate
string <date-time>

Timestamp when the report was created.

object (Delivery)

Delivery configuration for a report.

description
string

Report description to display in the Polaris UI, and in emails and webhooks.

disabled
boolean

Disables the report. Polaris doesn't evaluate disabled reports or send notifications.

number or string
Default: 500

Maximum number of rows to include in the report attachment. Defaults to 500.

enforceDecimalFormatting
boolean
Default: false

Formats numeric values in the report attachment as decimals.

object

Visualization definition for classic data cubes. This is not applicable to Polaris.

object (ExploreEssence)

State of a visualization in the Explore View

externalEmails
Array of strings <email> [ items <email > ]

External email addresses to receive report notications.

object (FacetEssence)

State of a visualization in the Pivot 2 view

fileFormat
string
Default: "csv"
Enum: "csv" "tsv" "xlsx" "json"

Format of the report data attachment. Defaults to CSV.

id
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

owner
string (Identifier) [ 1 .. 255 ] characters

Asset ID.

preferredView
string
Default: "pivot1"
Enum: "pivot1" "pivot2" "explore"

View to use when viewing the report in Polaris. Defaults to pivot1. When supplying a facetEssence, set to pivot2. When supplying an exploreEssence, set to explore.

any (AccessList)

Configure user access to the asset.

any (AccessList)

Configure user access to the asset.

sendDataFile
boolean
Default: true

Sends the report data as an attachment.

sendEmail
boolean

Sends email notifications to the report recipients when the report is generated.

object (TimeFrame)
timezone
string
Default: "Etc/UTC"

Timezone to use when evaluating report criteria. Defaults to UTC.

title
string

Report title to display in the Polaris UI, and in emails and webhooks.

property name*
additional property
any

Responses

Request samples

Content type
application/merge-patch+json
{
  • "id": "wikipedia-1234",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "owner": "wikipedia-1234",
  • "title": "My report",
  • "description": "string",
  • "disabled": true,
  • "delivery": {
    },
  • "preferredView": "pivot1",
  • "timeFrame": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "admins": {
    },
  • "readAccess": {
    },
  • "recipients": {
    },
  • "externalEmails": [
    ],
  • "timezone": "America/Los_Angeles",
  • "sendDataFile": true,
  • "addTotalRowToFile": false,
  • "fileFormat": "csv",
  • "downloadLimit": 500,
  • "enforceDecimalFormatting": false,
  • "sendEmail": true
}

Response samples

Content type
application/json
{
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdBy": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "id": "wikipedia-1234",
  • "creationDate": "2019-08-24T14:15:22Z",
  • "owner": "wikipedia-1234",
  • "title": "My report",
  • "description": "string",
  • "disabled": true,
  • "delivery": {
    },
  • "preferredView": "pivot1",
  • "timeFrame": {
    },
  • "essence": { },
  • "facetEssence": {
    },
  • "exploreEssence": {
    },
  • "admins": {
    },
  • "readAccess": {
    },
  • "recipients": {
    },
  • "externalEmails": [
    ],
  • "timezone": "America/Los_Angeles",
  • "sendDataFile": true,
  • "addTotalRowToFile": false,
  • "fileFormat": "csv",
  • "downloadLimit": 500,
  • "enforceDecimalFormatting": false,
  • "sendEmail": true
}

Delete a report

Deletes a report.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Report ID.

Responses

Response samples

Content type
application/json
{
  • "code": "ObjectNotFound",
  • "message": "The project was not found."
}

Get report evaluations

Returns all evaluations for a specified report.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Report ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Get report evaluation details

Returns information for a single report evaluation.

Authorizations:
bearerAuthapiKeyAuth
path Parameters
evaluationId
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Evaluation ID.

id
required
string (Identifier) [ 1 .. 255 ] characters
Example: wikipedia-1234

Report ID.

Responses

Response samples

Content type
application/json
{
  • "id": "wikipedia-1234",
  • "report": {
    },
  • "sendDate": "2019-08-24T14:15:22Z",
  • "errors": [
    ]
}

API Keys v1

Create and manage API keys for authentication to Polaris APIs.

List all API keys

Returns a list of all the API keys in redacted form.

Authorizations:
apiKeyAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create an API key

Creates an API key.

Authorizations:
apiKeyAuthbearerAuth
Request Body schema: application/json
required

An API key request.

description
string

A human-readable description provided by the user.

name
string

A human-readable name provided by the user.

Array of PermissionRepresentation (object) or strings

The list of permissions for the API key.

Responses

Request samples

Content type
application/json
{
  • "name": "Visualization key",
  • "description": "Visualization team API key",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "name": "Visualization key",
  • "description": "Visualization team API key",
  • "apiKey": "string",
  • "redactedApiKey": "pok_YxNxd...2xixwf",
  • "permissions": [
    ],
  • "createdBy": {
    },
  • "lastModifiedBy": {
    },
  • "createdOn": "2021-06-06T00:00:00.000Z",
  • "lastModifiedOn": "2021-06-06T00:00:00.000Z"
}

Get API key details

Returns information for a single API key.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The API key ID.

Responses

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "name": "Visualization key",
  • "description": "Visualization team API key",
  • "apiKey": "string",
  • "redactedApiKey": "pok_YxNxd...2xixwf",
  • "permissions": [
    ],
  • "createdBy": {
    },
  • "lastModifiedBy": {
    },
  • "createdOn": "2021-06-06T00:00:00.000Z",
  • "lastModifiedOn": "2021-06-06T00:00:00.000Z"
}

Update an API key

Updates an API key.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The API key ID.

Request Body schema: application/json
required
description
string

A human-readable description provided by the user.

name
string

A human-readable name provided by the user.

Array of PermissionRepresentation (object) or strings

The list of permissions for the API key.

Responses

Request samples

Content type
application/json
{
  • "name": "Visualization key",
  • "description": "Visualization team API key",
  • "permissions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "name": "Visualization key",
  • "description": "Visualization team API key",
  • "apiKey": "string",
  • "redactedApiKey": "pok_YxNxd...2xixwf",
  • "permissions": [
    ],
  • "createdBy": {
    },
  • "lastModifiedBy": {
    },
  • "createdOn": "2021-06-06T00:00:00.000Z",
  • "lastModifiedOn": "2021-06-06T00:00:00.000Z"
}

Delete an API key

Deletes an API key.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The API key ID.

Responses

Response samples

Content type
application/json
{ }

Get details for the API key used to authenticate this request

Returns information for the API key used to authenticate to the Polaris API.

Authorizations:
apiKeyAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "permissions": [
    ]
}

Network policy v1

Create and manage network policies that control API access to Polaris projects.

Network policy restrictions apply to regional API resources only. Regional APIs operate at the project level and are only accessible within the cloud service provider and region where Polaris hosts your project. To learn more about the difference between regional and global API resources, see Polaris API resources.

Get the network policy

Returns the network policy for a specified project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
required
object (Project)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "entries": {
    }
}

Update the network policy

Updates the network policy for a specified project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
required
object (Project)
Example: efebfbc4-79fe-41f8-beb9-b399c1584e28

Project ID.

Request Body schema: application/merge-patch+json
required

Network policy configuration to apply to the project.

enabled
required
boolean

Enable the network policy. When you set enabled to false, Polaris retains the network policy without enforcing it and accepts API requests from any IP address.

required
object

Container that holds network policy details for each specified IPv4 address or CIDR.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "enabled": true,
  • "entries": {
    }
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "entries": {
    }
}

Identity management v1

View permissions, create and manage users and groups.

List all permissions

Returns all permissions.

Authorizations:
apiKeyAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

List all users

Returns all users.

Authorizations:
apiKeyAuthbearerAuth
query Parameters
search
string

Filter users by a given string. Supported fields for search are username, email, firstName, lastName.

skip
integer >= 0
Default: 0

The number of user records to skip before returning top items.

top
integer [ 1 .. 100 ]
Default: 100

The maximum number of records to return.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "count": 0
}

Create a user

Creates a user.

Authorizations:
apiKeyAuthbearerAuth
Request Body schema: application/json
required

A user to be created.

actions
Array of any
Items Enum: "VERIFY_EMAIL" "UPDATE_PASSWORD"

The list of tasks a user must complete before being able to login.

enabled
boolean
Default: true

Flag to indicate the user is enabled.

firstName
string

The user's first name.

Array of objects (GroupRepresentation)

The list of groups the user belongs to.

lastName
string

The user's last name.

Array of objects (PermissionRepresentation)

The list of permissions individually assigned to the user.

username
string

The username for the user. The username must be a valid email address. Once set, username cannot be modified.

Responses

Request samples

Content type
application/json
{
  • "username": "user@email.com",
  • "firstName": "string",
  • "lastName": "string",
  • "enabled": true,
  • "permissions": [
    ],
  • "groups": [
    ],
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "username": "user@email.com",
  • "email": "user@email.com",
  • "firstName": "string",
  • "lastName": "string",
  • "enabled": true,
  • "emailVerified": false,
  • "permissions": [
    ],
  • "groups": [
    ],
  • "identities": [
    ],
  • "actions": [
    ],
  • "createdOn": "2021-06-06T00:00:00.000Z"
}

Get a user

Returns information for a specific user.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The user ID.

Responses

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "username": "user@email.com",
  • "email": "user@email.com",
  • "firstName": "string",
  • "lastName": "string",
  • "enabled": true,
  • "emailVerified": false,
  • "permissions": [
    ],
  • "groups": [
    ],
  • "identities": [
    ],
  • "actions": [
    ],
  • "createdOn": "2021-06-06T00:00:00.000Z"
}

Update a user

Updates a user.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The user ID.

Request Body schema: application/json
required
actions
Array of any
Items Enum: "VERIFY_EMAIL" "UPDATE_PASSWORD"

The list of tasks a user must complete before being able to login.

enabled
boolean
Default: true

Flag to indicate the user is enabled.

firstName
string

The user's first name.

Array of objects (GroupRepresentation)

The list of groups the user belongs to.

lastName
string

The user's last name.

Array of objects (PermissionRepresentation)

The list of permissions individually assigned to the user.

username
string

The username for the user. The username must be a valid email address. Once set, username cannot be modified.

Responses

Request samples

Content type
application/json
{
  • "username": "user@email.com",
  • "firstName": "string",
  • "lastName": "string",
  • "enabled": true,
  • "permissions": [
    ],
  • "groups": [
    ],
  • "actions": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "username": "user@email.com",
  • "email": "user@email.com",
  • "firstName": "string",
  • "lastName": "string",
  • "enabled": true,
  • "emailVerified": false,
  • "permissions": [
    ],
  • "groups": [
    ],
  • "identities": [
    ],
  • "actions": [
    ],
  • "createdOn": "2021-06-06T00:00:00.000Z"
}

Delete a user

Deletes a user.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The user ID.

Responses

Response samples

Content type
application/json
{ }

List permissions applied to a user

Returns all permissions applied to a user through group membership. For more information, see Permissions reference.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The user ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

List all groups

Returns all groups.

Authorizations:
apiKeyAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Create a group

Creates a group.

Authorizations:
apiKeyAuthbearerAuth
Request Body schema: application/json
required

A group to be created.

name
string

The group name.

Array of objects (PermissionRepresentation)

The list of permissions assigned to the group.

userCount
integer

The number of users assigned to this group.

Responses

Request samples

Content type
application/json
{
  • "name": "Data Manager",
  • "permissions": [
    ],
  • "userCount": 0
}

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "name": "Data Manager",
  • "readOnly": true,
  • "permissions": [
    ],
  • "userCount": 0
}

Get a group

Returns information for a specific group.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The group ID.

Responses

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "name": "Data Manager",
  • "readOnly": true,
  • "permissions": [
    ],
  • "userCount": 0
}

Update a group

Updates a group.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The group ID.

Request Body schema: application/json
required
name
string

The group name.

Array of objects (PermissionRepresentation)

The list of permissions assigned to the group.

userCount
integer

The number of users assigned to this group.

Responses

Request samples

Content type
application/json
{
  • "name": "Data Manager",
  • "permissions": [
    ],
  • "userCount": 0
}

Response samples

Content type
application/json
{
  • "id": "5xb1d143-f6x6-455x-x091-fbxa85xbx7x0",
  • "name": "Data Manager",
  • "readOnly": true,
  • "permissions": [
    ],
  • "userCount": 0
}

Delete a group

Deletes a group.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The group ID.

Responses

Response samples

Content type
application/json
{ }

List users who are members of a group

Returns all members for a given group.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The group ID.

query Parameters
search
string

Filter users by a given string. Supported fields for search are username, email, firstName, lastName.

skip
integer >= 0
Default: 0

The number of user records to skip before returning top items.

top
integer [ 1 .. 100 ]
Default: 100

The maximum number of records to return.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ],
  • "count": 0
}

Add users to a group

Adds users to the specified group.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The group ID.

Request Body schema: application/json
required

Users to be added to the specified group.

Array
actions
Array of any
Items Enum: "VERIFY_EMAIL" "UPDATE_PASSWORD"

The list of tasks a user must complete before being able to login.

enabled
boolean
Default: true

Flag to indicate the user is enabled.

firstName
string

The user's first name.

Array of objects (GroupRepresentation)

The list of groups the user belongs to.

lastName
string

The user's last name.

Array of objects (PermissionRepresentation)

The list of permissions individually assigned to the user.

username
string

The username for the user. The username must be a valid email address. Once set, username cannot be modified.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{ }

Remove users from a group

Removes specific users from the group.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The group ID.

Request Body schema: application/json
required

Users to be removed from the group.

Array
actions
Array of any
Items Enum: "VERIFY_EMAIL" "UPDATE_PASSWORD"

The list of tasks a user must complete before being able to login.

enabled
boolean
Default: true

Flag to indicate the user is enabled.

firstName
string

The user's first name.

Array of objects (GroupRepresentation)

The list of groups the user belongs to.

lastName
string

The user's last name.

Array of objects (PermissionRepresentation)

The list of permissions individually assigned to the user.

username
string

The username for the user. The username must be a valid email address. Once set, username cannot be modified.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{ }

Audit v1

Retrieve audit logs for your Imply Polaris organization.

List all audit logs

Returns all audit logs for the organization.

Authorizations:
bearerAuth
query Parameters
from
string <date-time>

Filter audit logs that happened after the specified date.

ip
string <ipv4>

Filter audit logs by the IP address.

to
string <date-time>

Filter audit logs that happened before the specified date.

type
any (AuditEventType)
Enum: "IMPERSONATED" "LOGIN" "LOGIN_FAILED" "LOGOUT" "PASSWORD_RESET_REQUESTED" "PASSWORD_UPDATED" "USER_INVITE_ACCEPTED" "APIKEY_CREATED" "APIKEY_DELETED" "APIKEY_NAME_UPDATED" "APIKEY_DESCRIPTION_UPDATED" "APIKEY_PERMISSIONS_ADDED" "APIKEY_PERMISSIONS_REMOVED" "APIKEY_SCOPE_ALL_PROJECTS" "APIKEY_SCOPE_SPECIFIC_PROJECTS" "APIKEY_UPDATED" "GROUP_CREATED" "GROUP_DELETED" "GROUP_MEMBER_ADDED" "GROUP_MEMBER_REMOVED" "GROUP_NAME_CHANGED" "GROUP_PERMISSIONS_ADDED" "GROUP_PERMISSIONS_REMOVED" "GROUP_SCOPE_ALL_PROJECTS" "GROUP_SCOPE_SPECIFIC_PROJECTS" "GROUP_UPDATED" "USER_CREATED" "USER_DELETED" "USER_DISABLED" "USER_ENABLED" "USER_INVITE_SENT" "USER_NAME_CHANGED" "USER_PASSWORD_RESET" "USER_GROUPS_ADDED" "USER_GROUPS_REMOVED" "USER_UPDATED"

Filter audit logs by type.

user
string

Filter audit logs by the user ID.

Responses

Response samples

Content type
application/json
{
  • "values": [
    ]
}

Metrics export v1

Retrieve performance metrics for your Imply Polaris organization.

List all metrics

Returns metrics for your Polaris organization. Configure your monitoring tools to scrape this endpoint to collect performance metrics.

Authorizations:
apiKeyAuthbearerAuth
query Parameters
includeLegacyMetrics
boolean

Set to true to include all types of legacy metrics in the response.

Responses

Response samples

Content type
# HELP query_count The number of sql queries run against the datasource
# TYPE query_count gauge
query_count{table="[daily-spend]",region="us-east-1",} 2.0 1678302900000
query_count{table="[demo]",region="us-east-1",} 13.0 1678302900000
query_count{table="[flight-test]",region="us-east-1",} 1.0 1678302900000
query_count{table="[fresh-wiki-2]",region="us-east-1",} 1.0 1678302900000
query_count{table="[wikiticker]",region="us-east-1",} 1.0 1678302900000

Projects v1

Create, edit, and delete Polaris projects.

List all projects

Returns all projects.

To get all projects for the organization, use the global base URL https://ORGANIZATION_NAME.api.imply.io.

To get all projects in a specified region of the organization, use the regional base URL https://ORGANIZATION_NAME.REGION.CLOUD_PROVIDER.api.imply.io.

Authorizations:
apiKeyAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a project

Creates a project in a specified region.

Authorizations:
apiKeyAuthbearerAuth
Request Body schema: application/json
required

Configuration of the project to be created.

required
object (ObjectMeta)

Metadata to identify the project.

required
object (ProjectSpec)

Information about the plan and desired state of the project.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Get project details

Returns information for a single project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

The ID of the project.

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Update a project

Updates a project to a different plan or state. See Update a project for more information.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

ID of the project.

Request Body schema: application/merge-patch+json
required

Configuration to update the project to.

required
object (ObjectMeta)

Metadata to identify the project.

required
object (ProjectSpec)

Information about the plan and desired state of the project.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Delete a project

Deletes a project.

Authorizations:
apiKeyAuthbearerAuth
path Parameters
id
required
string

ID of the project.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Project v1 (deprecated)

The Project API has been deprecated in favor of the Projects API. For information about how to adopt the new API, see Migration guide for deprecated APIs.

View and manage your Polaris project plan.

List available project sizes Deprecated

Returns all supported Polaris project sizes for your organization. For more information about project sizes, see Billing structure.

Authorizations:
apiKeyAuthbearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get project details Deprecated

Returns information about the current project.

Authorizations:
apiKeyAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Update a project Deprecated

Updates a project to a different size or state. See Update a project for more information.

Authorizations:
apiKeyAuthbearerAuth
Request Body schema: application/merge-patch+json
required

Configuration to update the project to.

required
object (ObjectMeta)

Metadata to identify the project.

required
object (ProjectSpec)

Information about the plan and desired state of the project.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    },
  • "status": {
    }
}

Delete a project Deprecated

Deletes a project.

Authorizations:
apiKeyAuthbearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}