OMomniapp
Connections

Create connection

Changed on

Create a new database connection. The request body varies by dialect - see dialect-specific documentation for required fields.

post/api/v1/connections

Request

  • Base URL
    https://omniapp.co (the document declares no server; this is the origin it was published from)
  • URL
    https://omniapp.co/api/v1/connections
  • Auth
    HTTP bearer

Request body

acceptsLicenseboolean

Acceptance of the license terms. Required for Oracle connections.

allowsUserSpecificTimezonesboolean

Whether to allow users to specify their own timezones

alwaysScopeViewNamesboolean

Whether to always include schema (and catalog) prefixes in generated view names, even for tables in the default schema. Defaults to true for dialects that support multiple catalogs, false otherwise.

authenticationTypestring

Authentication type. Dialect-specific; known values are aws-access-key, aws-cross-account-role, databricks-oauth-m2m, databricks-personal-access-token, databricks-oauth-user, mssql-sql-authentication, mssql-active-directory-password, mssql-active-directory-service-principal, snowflake-oauth-user, snowflake-external-oauth-user, snowflake-password, snowflake-keypair, bigquery-oauth-user, bigquery-byo-oauth-user, bigquery-service-account, bigquery-workload-identity-federation. Applicable for BigQuery, MSSQL, Snowflake, Databricks, and Athena.

awsRoleArnstring

AWS IAM role ARN. Applicable for Athena only.

baseRolestring

The default role for users accessing the connection: one of NO_ACCESS, VIEWER, RESTRICTED_QUERIER, QUERIER, MODELER, CONNECTION_ADMIN, or the name of a custom role in the organization. QUERY_TOPICS, the stored name of RESTRICTED_QUERIER, is also accepted. An empty string is treated as omitted; any other value is rejected and no connection is created.

databasestring

The default database/catalog to connect to. For BigQuery, this is the project ID. For Athena, this is the data catalog.

defaultSchemastring

The default schema to use. Tables in it are queried without a schema prefix.

dialect'bigquery' | 'mysql' | 'postgres' | 'redshift' | 'exasol' | 'snowflake' | 'motherduck' | 'mssql' | 'fabric' | 'databricks' | 'databricks_lakebase' | 'clickhouse' | 'trino' | 'athena' | 'starrocks' | 'mariadb' | 'oracle' | 'sap_hana' required

The database dialect

enableDbSemanticLayerIntegrationboolean

Enable the dialect-native semantic layer integration. Applicable for Snowflake and Databricks.

enableDbSemanticLayerTopicsboolean

Enable the dialect-native semantic layer topics. Applicable for Snowflake and Databricks.

externalOauthAudiencestring

External OAuth audience claim. Applicable for Snowflake.

externalOauthAuthorizationUrlstring uri

External OAuth authorization URL (must be HTTPS). Applicable for Snowflake.

externalOauthTokenUrlstring uri

External OAuth token URL (must be HTTPS). Applicable for Snowflake.

hoststring

The hostname or IP address of the database server. For Snowflake, provide only the account identifier.

hostOverridestring

Network hostname used to connect to Snowflake. When using a proxy, set host to the Snowflake account identifier.

includeOtherCatalogsstring[]

Other catalogs/databases to include. Only applicable for databases that support multi-catalog queries.

includeSchemasstring[]

Schemas to include. Omit it or send an empty array to include all schemas.

inferRelationshipsFromColumnNamesboolean

Whether to infer relationships from column-name conventions during schema refresh. Defaults to true.

inferRelationshipsFromForeignKeysboolean

Whether to infer relationships from declared foreign keys during schema refresh. Currently honored for Postgres and Snowflake.

maxBillingBytesinteger

Maximum bytes that can be billed for a BigQuery query. Applicable for BigQuery only.

namestring required

A descriptive name for the connection

oauthClientIdstring

OAuth client ID for admin schema refresh. Applicable for Snowflake and Databricks.

oauthClientSecretUnencryptedstring

OAuth client secret for admin schema refresh. Applicable for Snowflake and Databricks.

offloadedSchemasstring[]

Schemas whose tables should be queried via the offloaded engine.

passwordUnencryptedstring

The password to authenticate with. May be omitted for BigQuery, Snowflake, and Athena; required for every other dialect, and must not be blank except for Trino. For BigQuery, this is the JSON service account key file content, required for service account authentication (the default). For Snowflake, omit it for keypair or OAuth authentication. For Athena, this is the AWS secret access key.

portinteger

The port number for the database connection. Not required for Snowflake, MotherDuck, BigQuery, Databricks, and Athena.

privateKeystring

An unencrypted RSA key for keypair authentication, in PKCS#8 or PKCS#1 PEM format. PKCS#1 keys are converted to PKCS#8, and Omni will automatically add PKCS#8 PEM headers if none are provided. Applicable for Snowflake only.

queryTimeoutSecondsinteger

The timeout in seconds for queries. Maximum value is 3600 (1 hour). Only applicable for databases that support query timeouts.

queryTimezonestring

The timezone to use for queries

regionstring

Required for BigQuery and Athena connections. For BigQuery, specify a region like "us". For Athena, specify an AWS region like "us-east-1".

scratchSchemastring

Schema to use for data input (upload) tables. If not specified, a suitable default will be chosen.

strictEncryptionboolean

Use strict encryption (encrypt=strict, TDS 8.0): the connection starts with TLS and always validates the server certificate, ignoring trustServerCertificate. The endpoint must support TDS 8.0 (SQL Server 2022 or later, Azure SQL). SQL Server only; ignored for other dialects.

systemTimezonestring

The timezone to use for the system

trustServerCertificateboolean

Whether to trust the server certificate. Applicable for MSSQL, Exasol, ClickHouse, Trino, and SAP HANA.

useMachineAuthboolean

Whether to authenticate using machine credentials (OAuth M2M). Applicable for Athena and Databricks.

useReadScalingboolean

Request read-only routing (ApplicationIntent=ReadOnly) for this connection. SQL Server only; ignored for other dialects. SQL Server falls back to the primary when no readable secondary is available; Omni's upload writes always use the primary.

usernamestring

The username to authenticate with. For BigQuery, this is the client email from the service account.

warehousestring

Required for Snowflake (specify the warehouse) and Databricks (specify the HTTP path). May be omitted for Snowflake OAuth connections, in which case each user's Snowflake default warehouse applies. Optional for Athena (specify the workgroup); defaults to "primary".

wifAudiencestring

Full resource name of the workload identity pool provider. Required for BigQuery workload identity federation authentication.

wifServiceAccountEmailstring

Service account to impersonate for BigQuery workload identity federation authentication. When omitted, the federated identity is used directly.

Example request

{
  "acceptsLicense": true,
  "alwaysScopeViewNames": true,
  "authenticationType": "snowflake-password",
  "awsRoleArn": "arn:aws:iam::123456789012:role/OmniAthenaRole",
  "baseRole": "QUERIER",
  "database": "analytics_db",
  "defaultSchema": "public",
  "dialect": "snowflake",
  "externalOauthAuthorizationUrl": "https://oauth.example.com/authorize",
  "externalOauthTokenUrl": "https://oauth.example.com/token",
  "host": "myaccount",
  "hostOverride": "myaccount.snowflakecomputing.com",
  "includeOtherCatalogs": [
    "other_project1",
    "other_project2"
  ],
  "includeSchemas": [
    "public",
    "analytics"
  ],
  "inferRelationshipsFromColumnNames": true,
  "maxBillingBytes": 1000000000,
  "name": "Production Warehouse",
  "offloadedSchemas": [
    "analytics_archive"
  ],
  "port": 5432,
  "queryTimeoutSeconds": 900,
  "queryTimezone": "NONE",
  "region": "us-east-1",
  "scratchSchema": "omni_scratch",
  "systemTimezone": "UTC",
  "username": "analytics_user",
  "warehouse": "COMPUTE_WH",
  "wifAudience": "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider",
  "wifServiceAccountEmail": "omni@my-project.iam.gserviceaccount.com"
}

Response

Connection created successfully

datastring uuid required

Created connection ID

successboolean required

Whether the operation succeeded

Example response

{
  "data": "550e8400-e29b-41d4-a716-446655440000",
  "success": true
}

Changes

  • 255b22cfc05fRevision changes
    • info

      added the new optional request property

  • 8a7600b8087eRevision changes
    • breaking

      removed the enum value CONNECTION_ADMIN of the request property

    • breaking

      removed the enum value MODELER of the request property

    • breaking

      removed the enum value NO_ACCESS of the request property

    • breaking

      removed the enum value QUERIER of the request property

    • breaking

      removed the enum value RESTRICTED_QUERIER of the request property

    • breaking

      removed the enum value VIEWER of the request property

    • breaking

      request property list-of-types was narrowed by removing types string from media type application/json

    • breaking

      the request property type changed from string to array

    • breaking

      the request property type changed from string to array

    • breaking

      the request property type changed from string to integer

    • warning

      the request property's max was set to 9007199254740991.00

    • warning

      the request property's min was set to 0.00

    • info

      the request property became optional