Connect to Semantic Layer via JDBC

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

Prerequisites

Before you begin, ensure you have:

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

Download the JDBC driver

Download the Coginiti Semantic Layer JDBC driver:

semantic-layer-jdbc-driver-1.0.0.jar

Version: 1.0.0

Once downloaded, you'll need to install it in your BI tool or application (see installation steps below).

Understanding the connection URL

The Semantic Layer JDBC driver uses the following URL format:

jdbc:coginiti://[host]:[port][/?param1=val1&param2=val2&...]

Important: URI values must be URI-encoded if they contain spaces or special characters such as !, @, $, %, &, =, etc.

For example:

• Space: My Project → My%20Project
• @ symbol: user@company → user%40company
• Password p@ss!: p%40ss%21

Alternative: Connection parameters may also be supplied using a Properties object when using the JDBC Driver Manager. When using the Properties object, values should not be URI-encoded. See the Programmatic Connection section for examples.

Required parameters

Parameter	Description	Example
host	Coginiti Team/Enterprise server hostname or IP	localhost, semantic-layer.company.com
port	Semantic Layer service port	32010, 8080
user	Coginiti user credentials	janedoe
password	Coginiti user password	your-password
project	Project path with workspace prefix	@Personal/my-project, @Project Hub/retail/analytics

Optional parameters

Parameter	Description	Default	Example
semantic-layer	Semantic layer key from project.toml	Default layer	sales_domain, marketing_view
project-version	Specific project version (for projects from Project Hub)	Latest version	1.0.0, 2.3.1
useEncryption	Enable TLS/SSL encryption	true	true, false

Basic connection setup

Step 1: Install the JDBC driver

1. Download the driver: Download the driver from the Download section above
2. Place the driver: Copy the JAR file to your BI tool's JDBC drivers directory
3. Register the driver: Most tools auto-discover JDBC drivers; some may require manual registration

Step 2: Construct the connection URL

Build your connection URL using the required parameters:

jdbc:coginiti://localhost:32010/?user=janedoe&password=secret&project=@Personal/my-analytics-project

URL breakdown:

• jdbc:coginiti:// - Driver protocol
• localhost:32010 - Server and port
• user=janedoe - Your Coginiti credentials
• password=secret - Your password
• project=@Personal/my-analytics-project - Project path with workspace prefix

Step 3: Test the connection

1. Open your BI tool (Tableau, Power BI, DBeaver, etc.)
2. Select "Other Database (JDBC)" or similar option
3. Enter the connection URL you constructed
4. Test the connection to verify it works
5. Save the connection once successful

Common connection scenarios

Connecting to a specific semantic layer

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

jdbc:coginiti://localhost:32010/?user=admin&password=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:

jdbc:coginiti://localhost:32010/?useEncryption=false&user=admin&password=secret&project=@Shared/retail/analytics

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:

jdbc:coginiti://localhost:32010/?user=admin&password=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:

jdbc:coginiti://localhost:32010/?user=janedoe&password=secret&project=@Personal/my-analytics

Shared workspace

For projects in the shared workspace:

jdbc:coginiti://localhost:32010/?user=janedoe&password=secret&project=@Shared/team-analytics

Project Hub workspace

For projects in the Project Hub with folder structure:

jdbc:coginiti://localhost:32010/?user=janedoe&password=secret&project=@Project Hub/retail/sales-analytics

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

Programmatic connection

When connecting programmatically, you can supply connection parameters in two ways:

Method 1: Connection URL with URI-encoded parameters

Parameters are included in the URL string and must be URI-encoded:

import java.sql.*;

public class SemanticLayerConnection {
    public static void main(String[] args) {
        // Parameters with special characters must be URI-encoded in URL
        String url = "jdbc:coginiti://localhost:32010/?" +
                     "user=janedoe&" +                       // janedoe
                     "password=p%40ss%21&" +                 // p@ss!
                     "project=%40Personal%2FMy%20Project";   // @Personal/My Project

        try (Connection conn = DriverManager.getConnection(url)) {
            // Use connection
            System.out.println("Connected successfully!");
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

Method 2: Properties object (no URI encoding)

Parameters are supplied via Properties object and should not be URI-encoded:

import java.sql.*;
import java.util.Properties;

public class SemanticLayerConnection {
    public static void main(String[] args) {
        String url = "jdbc:coginiti://localhost:32010/";

        // Create properties with unencoded values
        Properties props = new Properties();
        props.setProperty("user", "janedoe");        // No encoding
        props.setProperty("password", "p@ss!");                // No encoding
        props.setProperty("project", "@Personal/My Project"); // No encoding
        props.setProperty("semantic-layer", "sales_domain");

        try (Connection conn = DriverManager.getConnection(url, props)) {
            // Use connection
            System.out.println("Connected successfully!");
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

Related documentation

• Semantic Layer Overview - Understanding semantic layer concepts
• Semantic Model Reference - Complete SMDL specification
• Database Connections - General database connection guidance
• Connection Templates - Managing connection configurations

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 URL (sanitized, without password)
   • Error messages
   • Client tool version
   • Server logs (if accessible)