Skip to main content

Connect to Semantic Layer via ODBC

This guide shows you how to connect third-party BI tools and applications to Coginiti's Semantic Layer using the ODBC driver on Windows.

Prerequisites​

Before you begin, ensure you have:

  • Coginiti Team or Enterprise installed and running
  • A project with a configured Semantic Layer
  • 64-bit Windows
  • Coginiti Semantic Layer ODBC driver (see Download section below)
  • Valid Coginiti user credentials with access to the project

Download the ODBC driver​

Download the Coginiti Semantic Layer ODBC driver:

semantic-layer-odbc-driver-1.0.0-win64.msi

Version: 1.0.0

The installer registers an ODBC driver named Coginiti Semantic SQL ODBC Driver (see installation steps below).

Install the driver​

  1. Run the installer: Double-click the downloaded .msi file and follow the prompts.
  2. Complete the installation: Accept the defaults unless your environment requires otherwise.
  3. Verify registration: Open the 64-bit ODBC Data Source Administrator (search "ODBC Data Sources (64-bit)" in the Windows Start menu) and open the Drivers tab. Confirm that Coginiti Semantic SQL ODBC Driver appears in the list.

Understanding the connection string​

The Semantic Layer ODBC driver is configured with a standard ODBC connection string of Key=Value; pairs:

Driver={Coginiti Semantic SQL ODBC Driver};HOST=coginiti.company.com;PORT=443;UID=janedoe;PWD=secret;project=@Personal/my-analytics

Required parameters​

ParameterDescriptionExample
DriverRegistered ODBC driver name{Coginiti Semantic SQL ODBC Driver}
HOSTCoginiti Team/Enterprise server hostname or IPcoginiti.company.com
PORTCoginiti Team/Enterprise server port443
UIDCoginiti user credentialsjanedoe
PWDCoginiti user passwordyour-password
projectProject path with workspace prefix@Personal/my-project

Optional parameters​

ParameterDescriptionDefaultExample
semantic-layerSemantic layer key from project.tomlDefault layersales_domain, marketing_view
project-versionSpecific project version (for projects from Project Hub)Latest version1.0.0, 2.3.1
useEncryptionEnable TLS/SSL encryptiontruetrue, false

A DSN (Data Source Name) stores the connection settings under a name that BI tools can select. This is the most common path for tools such as Excel, Power BI, and Tableau on Windows.

Step 1: Add a new data source​

  1. Open the 64-bit ODBC Data Source Administrator (search "ODBC Data Sources (64-bit)" in the Windows Start menu).
  2. Choose the User DSN tab (visible only to you) or the System DSN tab (visible to all users on the machine).
  3. Click Add.
  4. Select Coginiti Semantic SQL ODBC Driver from the list and click Finish.

A configuration dialog titled Configure Apache Arrow Flight SQL opens. This is expected — the driver is built on Apache Arrow Flight SQL.

Step 2: Configure the Common tab​

Under Connection settings:

  • Data Source Name — a name for this DSN (for example, Coginiti). BI tools use this name to select the connection.
  • Host Name — your Coginiti server hostname or IP (maps to HOST).
  • Port — your Coginiti server port, for example 443 (maps to PORT).

Under Authentication settings:

  • Authentication Type — leave set to Basic Authentication.
  • User — your Coginiti user name (maps to UID).
  • Password — your Coginiti password (maps to PWD).

The Authentication Token field and other authentication types are not covered by this guide.

Step 3: Configure the Advanced tab​

  • Use Encryption — check this if your Coginiti server uses TLS (maps to useEncryption). The Certificate, Use System Certificate Store, and Disable Certificate Verification options let you control certificate handling.
  • Advanced properties — project, semantic-layer, and project-version are not first-class fields, so add them here. Click Add and enter:
    • project (required) — your project path, for example @Personal/my-analytics.
    • semantic-layer (optional) — the semantic layer key, if your project defines more than one.
    • project-version (optional) — a specific version for projects from the Project Hub.

Step 4: Test and save​

  1. Click Test Connection to verify the settings.
  2. Click OK to save the DSN.

Your BI tool can now connect by selecting this DSN by name.

Option B: DSN-less connection string​

Applications and BI tools that accept a raw ODBC connection string can connect without creating a DSN:

Driver={Coginiti Semantic SQL ODBC Driver};HOST=coginiti.company.com;PORT=443;UID=janedoe;PWD=secret;project=@Personal/my-analytics

Connection string breakdown:

  • Driver={Coginiti Semantic SQL ODBC Driver} - The registered driver name
  • HOST=coginiti.company.com - Coginiti server host
  • PORT=443 - Coginiti server port
  • UID=janedoe - Your Coginiti credentials
  • PWD=secret - Your password
  • project=@Personal/my-analytics - Project path with workspace prefix

Common connection scenarios​

Connecting to a specific semantic layer​

If your project defines multiple semantic layers, specify which one to use:

Driver={Coginiti Semantic SQL ODBC Driver};HOST=coginiti.company.com;PORT=443;UID=admin;PWD=secret;project={@Project Hub/retail/analytics};semantic-layer=sales_domain

This connects to the sales_domain semantic layer defined in your project's project.toml.

Connecting with SSL/TLS encryption​

Encryption is enabled by default. For development environments where you need to disable encryption:

Driver={Coginiti Semantic SQL ODBC Driver};HOST=coginiti.company.com;PORT=443;UID=admin;PWD=secret;project={@Shared/retail/analytics};useEncryption=false

Important: Always use encryption in production environments. Ensure your Coginiti server is configured with valid SSL certificates.

Connecting to a specific project version​

When working with versioned projects from the Project Hub:

Driver={Coginiti Semantic SQL ODBC Driver};HOST=coginiti.company.com;PORT=443;UID=admin;PWD=secret;project={@Project Hub/retail/analytics};project-version=1.5.0

If project-version is omitted, the connection uses the latest version.

Workspace prefix examples​

Projects in Coginiti are organized into workspaces. The project path must include the workspace prefix:

Personal workspace​

For projects in your personal workspace:

Driver={Coginiti Semantic SQL ODBC Driver};HOST=coginiti.company.com;PORT=443;UID=janedoe;PWD=secret;project=@Personal/my-analytics

Shared workspace​

For projects in the shared workspace:

Driver={Coginiti Semantic SQL ODBC Driver};HOST=coginiti.company.com;PORT=443;UID=janedoe;PWD=secret;project=@Shared/team-analytics

Project Hub workspace​

For projects in the Project Hub with folder structure (note the braces around the path, which contains a space):

Driver={Coginiti Semantic SQL ODBC Driver};HOST=coginiti.company.com;PORT=443;UID=janedoe;PWD=secret;project={@Project Hub/retail/sales-analytics}

Important: Always include the workspace prefix (@Personal, @Shared, @Project Hub) in the project path.

Programmatic connection (Python)​

You can connect from Python using the pyodbc library.

Connect via a DSN​

If you have configured a DSN (see Option A), reference it by name:

import pyodbc

conn = pyodbc.connect("DSN=Coginiti;UID=janedoe;PWD=secret")

cursor = conn.cursor()
cursor.execute("SELECT * FROM your_semantic_view")
for row in cursor.fetchall():
    print(row)

Connect via a DSN-less connection string​

Supply the full connection string, including the driver name:

import pyodbc

conn_str = (
    "Driver={Coginiti Semantic SQL ODBC Driver};"
    "HOST=coginiti.company.com;"
    "PORT=443;"
    "UID=janedoe;"
    "PWD=secret;"
    "project=@Personal/my-analytics"
)

conn = pyodbc.connect(conn_str)

cursor = conn.cursor()
cursor.execute("SELECT * FROM your_semantic_view")
for row in cursor.fetchall():
    print(row)

Troubleshooting​

Data source name not found​

If you see the following error:

[Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified

This means the DSN name is misspelled, the DSN was created in a different scope (User vs. System), or the driver is not registered. Verify that:

  • The DSN name in your connection matches the one you created.
  • The Coginiti Semantic SQL ODBC Driver appears on the Drivers tab of the ODBC Data Source Administrator. If it does not, reinstall the driver.

Driver does not appear / 32-bit vs 64-bit mismatch​

The Coginiti Semantic Layer ODBC driver is 64-bit. If the driver does not appear when adding a DSN, you are likely using the 32-bit ODBC Data Source Administrator, or a 32-bit application (such as older versions of Microsoft Office/Excel).

To resolve this:

  • Always configure the DSN using the 64-bit ODBC Data Source Administrator ("ODBC Data Sources (64-bit)").
  • Use a 64-bit version of your BI tool or application.

Encryption or TLS handshake failures​

If the connection fails when encryption is enabled:

  • Ensure the useEncryption setting (the Use Encryption checkbox on the Advanced tab) matches your Coginiti server's configuration.
  • Verify that the server's SSL certificate is valid and trusted. On the Advanced tab, you can supply a certificate, use the system certificate store, or — for development only — disable certificate verification.

Getting support​

If you encounter issues not covered in this guide:

  1. Check server logs: Review Coginiti Team/Enterprise logs for detailed errors
  2. Test with Coginiti UI: Verify the semantic layer works within Coginiti
  3. Contact support: Reach out to Coginiti support with:
    • Connection string (sanitized, without password)
    • Error messages
    • Client tool version
    • Server logs (if accessible)