2. Data source connections

A connection stores the details Groundzero needs to reach an external system: a database, a data warehouse, object storage, a SaaS application, a streaming service, an AI model provider, an MCP server or a Groundzero lakehouse. Datasets, ETL jobs, the lakehouse and AI features refer to connections by name, so you set a connection up once and reuse it everywhere.

Open Connections in the top navigation bar.

Overview#

What you can do#

When to use connections#

• You want a dataset (Designer) or an ETL job (DE/ML) to read from or write to an external system.
• You want Groundzero AI Chat or Agent Builder to use a model provider, an MCP server or another Groundzero agent service.
• You want the Lineage page to explain where data came from; lineage identifies assets by the connection they live on.
• You want to browse an object-storage bucket under My Files (see the Files and workspaces chapter).

Who can do what#

Every signed-in user can open the page, but what you see and can do depends on your permissions on the resource type "Connection". An administrator grants them in the admin console (Access Manager).

An administrator can grant permissions to a user or a group, either for all connections or for one connection. An explicit deny wins. Whoever creates a connection automatically receives All on it. If you see a "You do not have ... permissions" message, ask an administrator for the permission it names.

Create a connection#

Before you start, have the host name or address, the account or user name and the password or key for the system you want to reach. Ask the owner of that system if you do not know them.

1. Click New connection. The Add Connection dialog opens with a single field, Connection Type. Save and Test Connection are disabled.

   

2. Click Connection Type and type to filter the alphabetical list, or scroll. Each option shows the connector logo.

   

3. Pick a type. The form for that connector appears. The first field is always Connection Name. Fill in the remaining fields (see the connector reference below).

   

4. Click Test Connection (optional but recommended). A success or failure message appears as a notification.

   

5. Click Save. The dialog closes, the list reloads and the notification "Connection created successfully" appears. Your new connection is now in the list, and datasets and jobs can use it by name.

   

Example: connect PostgreSQL in five steps#

1. Click New connection and choose PostgreSQL.
2. Enter Connection Name acme-orders-db.
3. Enter Server orders.acme-retail.example.com, Database orders, keep Port 5432, and enter Username analytics_reader and the Password.
4. Click Test Connection. You should see "Test connection succeeded".
5. Click Save. acme-orders-db appears in the list.

Connection name rules#

A name must start with a letter and may contain letters, digits and single hyphens in the middle: no spaces, no underscores, no hyphen at the end and no two hyphens in a row. Names are unique per site.

When Save and Test Connection are enabled#

Both buttons stay disabled until all of these are true:

• you picked a connection type;
• Connection Name is not blank;
• every field is filled in, except fields labelled "(optional)". Numbers (including 0) and True or False choices count as filled.

If Save stays disabled, look for a field that is not labelled "(optional)" and is still empty. This includes fields that look unimportant, such as a pre-filled default you cleared.

Messages you may see while creating#

Test a connection#

Test Connection uses the values currently in the form and never saves anything. While it runs, the button reads "Testing...". Test before you save, and again after you edit.

What a successful test says, by family:

When a test fails, read the message first. Typical ones are "Bucket does not exist", "Access denied to bucket" and "Container does not exist" for storage. For a database, the message is the database's own error (wrong password, host not reachable). If the message is only "Error occurred while testing connection", check the host, port and credentials.

When you edit an MCP Server connection and its token or header values are still masked, the test is blocked with "Re-enter or replace saved MCP credentials before testing this connection."

Find a connection#

The page loads every connection you may list. The header shows Last refreshed (Just now, N min ago, and so on) and the New connection button.

The toolbar#

Active filters appear as removable chips (for example Type: PostgreSQL) with a Clear all button. Changing a filter returns you to page 1.

The table#

Click a column header to sort ascending, click again to reverse. The footer states the sort (for example "Sorted by Name, ascending"). Page size is 20, 50 or 100 rows. Rows are keyboard focusable: press Enter on a focused row to open its details.

How the Category chip is chosen. AI provider: OpenAI, Anthropic, Bedrock, Cohere, Custom LLM, Fireworks, Gemini, Hugging Face, MCP, Groundzero Agents, Together, xAI. Lakehouse: lakehouse and Iceberg connections. Object storage: S3, Google Cloud Storage, Azure Blob and AI Chat Storage. Database: PostgreSQL, SQL Server, MySQL, Oracle, Redshift, Snowflake, BigQuery, Databricks, MongoDB and similar. Application: HubSpot, Salesforce, ServiceNow, Zoho, Shopify. Streaming: Event Hubs, Kafka, Kinesis. Everything else, for example Athena or Rest-API, is shown as "Data source".

View connection details#

Click a connection name, choose View details from the "..." menu, or press Enter on a focused row.

The dialog shows the connector logo, name, type and category, a summary (Owner, Updated; Workspace only if present), and Configured details: one row per setting, with a readable label such as Bucket Name. Values that look secret (password, secret, token, credential, private key, access key, API key, account key, client secret, security token) show a lock and *****, and nobody, including an administrator, can display them again. Other values have a copy button. The footer buttons are Edit and Close.

Edit a connection#

Click the pencil icon (Edit <name>) or Edit in the details dialog.

1. Change the fields you need. The Type cannot be changed; Connection Name can.
2. Type every secret again. Non-secret values are pre-filled, but secrets arrive empty, so Save and Test Connection stay disabled until the form is complete. AI model provider forms and MCP Server show existing secrets as ............ and keep them if you leave them unchanged.
3. Click Test Connection, then Save. Save replaces the whole configuration. On success the notification reads "<Name> edited successfully".

Datasets and jobs refer to a connection by name, so renaming a connection can break them. Edit errors: the message returned, or "Unable to edit connections"; "Fill all required connection details before saving" when the form is incomplete. For MCP Server, if the stored secret is missing you see "Saved MCP credentials could not be preserved. Re-enter or replace them and try again."

Delete a connection#

1. Open the row menu (Open actions for <name>) and choose Delete.
2. Confirm in Delete Connection: "Are you sure you want to delete this connection <name>?".

On success the notification reads "Connection deleted successfully" and the list reloads. Failures show the message returned or "Unable to delete connections".

Connector reference#

The Connection Type list offers 66 connector types in families. For each family this section explains the fields they share once, then lists the fields each connector shows. Field names are the labels in the form. "(masked)" means the input hides what you type. "(optional)" means you may leave it empty. Defaults are what the form pre-fills.

Tips that apply to every connector:

• Create a dedicated user or key for Groundzero with only the access it needs. A read-only database user is enough for analytics.
• Copy values exactly. A trailing space or a wrong region is the most common reason a test fails.
• Use Test Connection before you save.

Relational databases#

Use these for operational databases and classic SQL servers.

Shared fields: Server (host name or address), Database, Port (the form pre-fills the usual port), Username and Password (masked). Ask your database administrator for the host and for a login that can read the tables you need.

Example: connect PostgreSQL. See "Example: connect PostgreSQL in five steps" above. The other relational connectors work the same way with their own port.

Common mistakes. Using the wrong port; pointing to a host that is only reachable inside your company network; leaving Password empty when editing, because secrets must be typed again.

Cloud data warehouses and lakehouse engines#

Use these for warehouses and analytics engines in the cloud.

Example: connect Snowflake. Choose Snowflake, name it acme-snowflake, enter Account acme-retail01, Database ANALYTICS, Schema PUBLIC, Username GZ_READER and the Password, then click Test Connection and Save.

Common mistakes. Pasting the full web address into Account; using a user without access to the chosen database or schema.

Other databases and search or vector stores#

Use these for document, graph, key-value, search, time-series, log and vector stores.

Common mistakes. Using a key for a different region or project; leaving the default port when your server uses another.

Object storage and file sources#

Use these for buckets, drives and file servers. Only AWS S3 buckets can be browsed under My Files.

Example: connect AWS S3. Choose AWS S3, name it acme-landing-bucket, enter Bucket Name acme-retail-landing, Region us-east-1, then the Access Key and Secret Access Key of a user that can read the bucket. Test Connection should report success. After you save, the bucket appears under My Files.

Common mistakes. A wrong bucket name or region; a key without access to the bucket ("Access denied to bucket"); JSON containing an empty value in Credentials File, which keeps Save disabled because every value must be filled.

Streaming#

Use these for event streams.

Example: connect Kafka. Choose Apache Kafka, name it acme-orders-stream, enter your Bootstrap Servers (host:port, comma separated if several), the Security Protocol and SASL Mechanism your cluster requires, then the API Key and API Secret, and Starting Offsets. Click Test Connection.

Common mistakes. Mismatched Security Protocol and SASL Mechanism; a key that has no access to the topic.

Applications and APIs#

Use these for SaaS applications and generic web APIs.

OAuth-style connectors (OneDrive, Sharepoint, Microsoft Dataverse, Zoho CRM) take the client ID, secret, tenant and refresh-token values pasted into text boxes. Copy them from the app registration in the source system.

Example: connect a REST API. Choose Rest-API, name it acme-pricing-api, enter Base URL https://api.acme-retail.example.com, Endpoint /v1/prices and AuthType. Click Test Connection.

Common mistakes. Putting the endpoint path in Base URL; an expired token.

AI model providers#

Use these for the models behind AI Chat and Agent Builder. Model-provider connections feed the model picker in AI Chat.

Shared fields: API Key (masked), a base URL that is pre-filled with the provider's standard address, and an optional Model.

Example: connect OpenAI. Choose OpenAI, name it acme-openai, paste the API Key, keep the default Base URL and click Test Connection. Success reads "Connection successful". The model then shows up in the AI Chat model picker.

Common mistakes. A key from a different provider or project; changing Base URL by accident. An edit form shows saved keys as ............ and keeps them if you do not change them.

MCP Server and Groundzero Agents#

Special connection types#

MCP Server#

The MCP form checks what you type. Server URL must be a public HTTPS URL without credentials or a fragment; otherwise the helper text "Use a public HTTPS URL without credentials or a fragment." appears. Transport is "Streamable HTTP" (default) or "Server-Sent Events". Auth Type is "No auth" (default), "Bearer token" (shows Bearer Token, masked) or "Custom headers" (Custom Headers JSON becomes required). Allowed Tools is a comma- or newline-separated list of tool names you permit. Timeout Seconds defaults to 30 and must be 1 to 300.

Test it: success reads "Test connection succeeded. Found N tool(s)." If it fails, check that the URL is public HTTPS and reachable.

Custom LLM#

Use this for a model behind your own HTTPS endpoint.

Groundzero Lakehouse#

Lakehouse URL is a host name only (without https://). Warehouse and database names are free text. Use a service account with access to that warehouse. See the Lakehouse chapter for how warehouses are created and how to copy the Lakehouse URL.

AI Chat Storage#

Uses the AWS S3 form. Its name is fixed to GZ-CHAT-STORAGE, only one may exist, and once it exists the type disappears from the type list.

Secrets#

• After you save, secret values show only as *****.
• Some fields show what you type: Azure Blob Account Key, Databricks Access Token, ElasticSearch API Key, HubSpot Access Token, Shopify Access Token, Weaviate API Key, Zoho Refresh Token, and the Credentials File fields of Google Cloud Storage, Google BigQuery and Google Drive. Avoid screen sharing while you fill them.
• When you edit a connection you retype its secrets, except for MCP Server and the AI model provider forms.

Limits#

Tips#

Troubleshooting#

Related features#

• Files and workspaces: browse S3 buckets that connections point to.
• Lakehouse: warehouses referenced by Groundzero Lakehouse connections.
• Data catalog and Data lineage: lineage identifies assets by the connection they belong to.
• Designer datasets and DE/ML jobs (Build documentation): read connections by name.