Integrations - Sphinx Doc

Overview

Integrations allow you to connect external data sources and cloud services to Sphinx. Once configured, Sphinx can automatically query your databases, read from cloud storage, and interact with your data infrastructure—all through natural language requests.

Supported Platforms

Databricks

Connect to Databricks workspaces for data analytics and ML workflows.

Snowflake

Query Snowflake data warehouses using PAT authentication.

SQL Databases

Connect to PostgreSQL, MySQL, SQL Server, and other SQL databases.

Google Cloud Platform

Access BigQuery, Cloud Storage, Vertex AI, and Firestore.

Amazon Web Services

Connect to S3, DynamoDB, Athena, and other AWS services.

Microsoft Azure

Access Blob Storage, Azure SQL, Key Vault, and more.

MongoDB

Query MongoDB databases and collections.

Custom Integration

Create your own integration with custom rules and secrets.

Setting Up Integrations

Open the Dashboard

Navigate to dashboard.prod.sphinx.ai and sign in.

Go to Integrations

Click Integrations in the sidebar navigation.

Add a new integration

Click Add Integration, select your service, and choose an authentication method.

Configure credentials

Enter your connection details and credentials. Give your integration a memorable name.

Use in notebooks

Ask Sphinx to query your data. It will automatically use your configured integrations.

Platform Configuration

Connect to Databricks workspaces to run SQL queries and access data lakes.

Authentication Methods

Method	Use Case
Personal Access Token	Individual access using a Databricks PAT

Required Fields

workspaceUrl

string

required

Your Databricks workspace URL (e.g., https://adb-123456789.12.azuredatabricks.net)

token

string

required

Your Databricks personal access token (starts with dapi...)

httpPath

string

SQL warehouse HTTP path (e.g., /sql/1.0/warehouses/abc123)

Example Usage

import sphinxai
from databricks import sql

token = await sphinxai.get_user_secret_value("integration/databricks/my-workspace/token")

connection = sql.connect(
    server_hostname="adb-123456789.12.azuredatabricks.net",
    http_path="/sql/1.0/warehouses/abc123",
    access_token=token
)

cursor = connection.cursor()
cursor.execute("SELECT * FROM my_table LIMIT 10")
result = cursor.fetchall()

Connect to Snowflake data warehouses for analytics and data processing.

Authentication Methods

Method	Use Case
Programmatic Access Token	Secure access using Snowflake PAT

Required Fields

accountIdentifier

string

required

Your Snowflake account identifier (e.g., xy12345.us-east-1 or myorg-myaccount)

username

string

required

Your Snowflake username

token

string

required

Programmatic access token from Snowflake

warehouse

string

Default warehouse to use (e.g., COMPUTE_WH)

database

string

Default database

schema

string

Default schema

Example Usage

import sphinxai
import snowflake.connector

token = await sphinxai.get_user_secret_value("integration/snowflake/production/token")

conn = snowflake.connector.connect(
    account="xy12345.us-east-1",
    user="my_username",
    password=token,
    warehouse="COMPUTE_WH",
    database="MY_DATABASE"
)

cursor = conn.cursor()
cursor.execute("SELECT * FROM my_table LIMIT 10")
print(cursor.fetchall())

Connect to PostgreSQL, MySQL, SQL Server, and other relational databases using SQLAlchemy.

Authentication Methods

Method	Use Case
Connection String	Use a database URL
Individual Credentials	Specify host, port, username, password separately

Connection String Method

databaseType

string

required

Database type: postgresql, mysql, mssql, etc.

connectionString

string

required

Full connection string (e.g., postgresql://user:pass@host:5432/dbname)

Individual Credentials Method

host

string

required

Database server hostname

port

string

required

Database port (default: 5432 for PostgreSQL)

database

string

required

Database name

username

string

required

Database username

password

string

required

Database password

sslMode

string

SSL mode: require, verify-full, disable

Example Usage

import sphinxai
from sqlalchemy import create_engine
import pandas as pd

connection_string = await sphinxai.get_user_secret_value("integration/sql/analytics-db/connectionString")
engine = create_engine(connection_string)

df = pd.read_sql("SELECT * FROM users LIMIT 100", engine)
print(df.head())

Connect to GCP services including BigQuery, Cloud Storage, Vertex AI, and Firestore.

Authentication Methods

Method	Use Case
Local Credentials	Use `gcloud` CLI authentication (development)
Service Account Key	Use a service account JSON key (production)

Local Credentials

Requires running gcloud auth application-default login first.

projectId

string

Default GCP project ID

location

string

Default region (e.g., us-central1)

This is a local credentials integration. It will NOT work if your environment is missing GCP credentials.

Service Account Key

projectId

string

required

GCP project ID

serviceAccountKey

string

required

Full service account JSON key

Example Usage

import sphinxai
import json
from google.cloud import bigquery
from google.oauth2 import service_account

key_json = await sphinxai.get_user_secret_value("integration/gcp/production/serviceAccountKey")
credentials = service_account.Credentials.from_service_account_info(json.loads(key_json))

client = bigquery.Client(project="my-project", credentials=credentials)
df = client.query("SELECT * FROM my_dataset.my_table LIMIT 100").to_dataframe()

Connect to AWS services including S3, DynamoDB, Athena, and more using Boto3.

Authentication Methods

Method	Use Case
Local Credentials	Use `~/.aws/credentials` or IAM roles
Access Key	Use IAM access key and secret

Local Credentials

Uses credentials already configured on your machine.

profile

string

AWS profile name (default: default)

region

string

Default AWS region (default: us-east-1)

This is a local credentials integration. It will NOT work if your environment is missing AWS credentials.

Access Key

accessKeyId

string

required

AWS Access Key ID

secretAccessKey

string

required

AWS Secret Access Key

region

string

required

AWS region

sessionToken

string

Temporary session token (for assumed roles)

Example Usage

import sphinxai
import boto3
import pandas as pd

secret_key = await sphinxai.get_user_secret_value("integration/aws/production/secretAccessKey")

session = boto3.Session(
    aws_access_key_id="AKIAIOSFODNN7EXAMPLE",
    aws_secret_access_key=secret_key,
    region_name="us-east-1"
)
s3 = session.client('s3')

response = s3.get_object(Bucket='my-bucket', Key='data.csv')
df = pd.read_csv(response['Body'])

Connect to Azure services including Blob Storage, SQL Database, and Key Vault.

Authentication Methods

Method	Use Case
Local Credentials	Use Azure CLI or environment variables
Service Principal	Use Azure AD application credentials

Local Credentials

Uses DefaultAzureCredential which tries Azure CLI, environment variables, and managed identity.

subscriptionId

string

Azure subscription ID

storageAccountName

string

Default storage account name

This is a local credentials integration. Run az login to authenticate before using.

Service Principal

tenantId

string

required

Azure AD tenant ID

clientId

string

required

Application (client) ID

clientSecret

string

required

Client secret

Example Usage

import sphinxai
from azure.identity import ClientSecretCredential
from azure.storage.blob import BlobServiceClient

client_secret = await sphinxai.get_user_secret_value("integration/azure/production/clientSecret")

credential = ClientSecretCredential(
    tenant_id="12345678-...",
    client_id="87654321-...",
    client_secret=client_secret
)

blob_service = BlobServiceClient(
    account_url="https://mystorageaccount.blob.core.windows.net",
    credential=credential
)

Connect to MongoDB databases for document-based data access.

Authentication Methods

Method	Use Case
Connection String	Standard MongoDB connection URI

Required Fields

connectionString

string

required

MongoDB connection string (e.g., mongodb+srv://user:[email protected]/dbname)

defaultDatabase

string

Default database to use

Example Usage

import sphinxai
from pymongo import MongoClient
import pandas as pd

connection_string = await sphinxai.get_user_secret_value("integration/mongodb/production/connectionString")

client = MongoClient(connection_string)
db = client["my_database"]

# Query documents
cursor = db["users"].find({"status": "active"}).limit(100)
df = pd.DataFrame(list(cursor))

Create a fully custom integration when none of the pre-built options fit your needs. Custom integrations let you define your own rules and secrets for any data source or service.

When to Use Custom Integrations

Connecting to an API or service not listed above
Using a proprietary or internal data system
Needing specialized authentication flows
Combining multiple services into one integration

Creating a Custom Integration

Name your integration

Choose a descriptive name (e.g., internal-api, legacy-database). This name is used in the rule path: integration/custom/{name}

Write your rules

Provide Markdown-formatted instructions that teach Sphinx how to connect to and use your service. Include:

Connection details
Authentication method
Example code snippets
Any special considerations

Add secrets (optional)

Define any credentials Sphinx needs to access your service. Each secret has a name and value.

Required Fields

name

string

required

A unique name for your integration (lowercase, no spaces)

ruleContent

string

required

Markdown content describing how to connect to and use your service

Optional Secrets

You can add any number of secrets. Each secret needs:

secretName

string

Name for the secret (e.g., apiKey, token, password)

secretValue

string

The secret value to store securely

Example: Custom API Integration

Rule Content:

## Internal Analytics API: my-analytics-api

Connect to our internal analytics API.

### Connection Details
- Base URL: https://analytics.internal.company.com/api/v2
- Authentication: Bearer token stored in secret `integration/custom/my-analytics-api/apiKey`

### Example Usage

\`\`\`python
import sphinxai
import requests

api_key = await sphinxai.get_user_secret_value("integration/custom/my-analytics-api/apiKey")

headers = {"Authorization": f"Bearer {api_key}"}
response = requests.get(
    "https://analytics.internal.company.com/api/v2/reports",
    headers=headers
)
data = response.json()
\`\`\`

Secrets:

apiKey: Your API key value

Custom integrations are powerful but require you to write clear instructions for Sphinx. The more detailed your rules, the better Sphinx will understand how to use your integration.

How Sphinx Uses Integrations

When you configure an integration, Sphinx:

Creates a Rule — Automatically generates instructions for connecting to your data source
Stores Secrets — Encrypts and securely stores your credentials
Provides Context — Teaches the AI how to authenticate and query your data

When you ask questions about your data, Sphinx:

Identifies which integration to use based on your question
Generates code that retrieves credentials from Sphinx secrets
Connects to your data source and runs queries
Returns results for analysis

You don’t need to remember connection strings or authentication code. Just ask Sphinx to “query the sales data from Snowflake” and it handles the rest.

Security

Credential Storage

All sensitive credentials (passwords, tokens, API keys) are encrypted before storage. Connection details are only accessed when explicitly used in your notebooks.

Local Credentials

For AWS, Azure, and GCP, “local credentials” options use credentials already on your machine. These don’t store any secrets in Sphinx—they rely on your local environment being properly configured.

Best Practices

Use service accounts or IAM roles with minimal required permissions
Rotate credentials regularly (every 90 days recommended)
Use separate integrations for production vs. development environments
Review and remove integrations you no longer need

Managing Integrations

Viewing Integrations

All configured integrations appear on the Integrations page in your dashboard. You can see:

Integration name
Service type
Authentication method
When it was created

Updating Credentials

To update an integration’s credentials:

Click on the integration in your dashboard
Update the fields you need to change
Click Save

Removing Integrations

To remove an integration:

Click on the integration in your dashboard
Click Delete
Confirm the deletion

Deleting an integration removes all associated secrets. Any notebooks relying on this integration will fail to authenticate until you reconfigure it.

Home

Extension

CLI

Agent

Configuration

​Overview

​Supported Platforms

Databricks

Snowflake

SQL Databases

Google Cloud Platform

Amazon Web Services

Microsoft Azure

MongoDB

Custom Integration

​Setting Up Integrations

​Platform Configuration

​Authentication Methods

​Required Fields

​Example Usage

​Authentication Methods

​Required Fields

​Example Usage

​Authentication Methods

​Connection String Method

​Individual Credentials Method

​Example Usage

​Authentication Methods

​Local Credentials

​Service Account Key

​Example Usage

​Authentication Methods

​Local Credentials

​Access Key

​Example Usage

​Authentication Methods

​Local Credentials

​Service Principal

​Example Usage

​Authentication Methods

​Required Fields

​Example Usage

​When to Use Custom Integrations

​Creating a Custom Integration

​Required Fields

​Optional Secrets

​Example: Custom API Integration

​How Sphinx Uses Integrations

​Security

​Managing Integrations

​Viewing Integrations

​Updating Credentials

​Removing Integrations

Overview

Supported Platforms

Setting Up Integrations

Platform Configuration

Authentication Methods

Required Fields

Example Usage

Authentication Methods

Required Fields

Example Usage

Authentication Methods

Connection String Method

Individual Credentials Method

Example Usage

Authentication Methods

Local Credentials

Service Account Key

Example Usage

Authentication Methods

Local Credentials

Access Key

Example Usage

Authentication Methods

Local Credentials

Service Principal

Example Usage

Authentication Methods

Required Fields

Example Usage

When to Use Custom Integrations

Creating a Custom Integration

Required Fields

Optional Secrets

Example: Custom API Integration

How Sphinx Uses Integrations

Security

Managing Integrations

Viewing Integrations

Updating Credentials

Removing Integrations