Snowflake

Create a Snowflake connector with its real config fields, test the connection, browse its tables, onboard one as a dataset, and run a governed query against it.

By the end of this page you will have a saved snowflake connector that reaches your account, a confirmed live connection test, a browse listing of the tables it exposes, one of those tables onboarded as a queryable dataset, and a first governed query returning rows from it. Once onboarded, the table becomes governed data: the engine queries it under a typed, validated contract, so results stay deterministic and auditable.

Prerequisites: an API key and a base URL (see Authentication), and Snowflake credentials — an account identifier, a user, a password, and the database you want to query. Use https://api.algenta.ai for Algenta cloud, or your own origin such as http://localhost:8000 for a self-hosted deployment.

A snowflake connector takes these config fields: account, user, password, and database are required for the structured form; warehouse and schema are optional. Alternatively, supply a single connection_string DSN of the form snowflake://user:password@account/database/schema?warehouse=WH. These are the only Snowflake fields the engine reads.

1

Set your credentials

Export your API key and base URL so every command below picks them up from the environment. Keep your Snowflake password in its own variable so it never appears in shell history inline.

export ALGENTA_API_KEY="$ALGENTA_API_KEY"
export ALGENTA_BASE_URL="https://api.algenta.ai"
export SNOWFLAKE_PASSWORD="$SNOWFLAKE_PASSWORD"

Verify the variables are set:

echo "${ALGENTA_API_KEY:?set ALGENTA_API_KEY}" >/dev/null && echo "key present"
echo "$ALGENTA_BASE_URL"
echo "${SNOWFLAKE_PASSWORD:?set SNOWFLAKE_PASSWORD}" >/dev/null && echo "password present"

Expected result: three lines print without error — key present, your base URL, and password present. If any line errors, export the missing variable before continuing.

2

Confirm the engine accepts snowflake

Ask the engine which connector types it supports and confirm snowflake is in the list.

curl -s "$ALGENTA_BASE_URL/v1/connectors/types" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"

Expected result: a JSON object with a types array that includes "snowflake", for example {"types": ["bigquery", "clickhouse", "postgres", "snowflake", ...]}. If snowflake is present, the next step's config shape is accepted.

3

Create the Snowflake connector

POST /v1/connectors stores the connection name, type, and credentials, and returns the connector with status: "untested". Fill in your real account (the Snowflake account identifier, such as xy12345.eu-central-1), user, database, and — recommended — a warehouse so queries have compute, plus an optional default schema.

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Analytics Warehouse\",
    \"connector_type\": \"snowflake\",
    \"config\": {
      \"account\": \"xy12345.eu-central-1\",
      \"user\": \"ANALYTICS\",
      \"password\": \"$SNOWFLAKE_PASSWORD\",
      \"warehouse\": \"COMPUTE_WH\",
      \"database\": \"SALES\",
      \"schema\": \"PUBLIC\"
    }
  }"

If you already have a Snowflake DSN, pass it as connection_string instead of the structured fields — the engine reads either form:

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Analytics Warehouse\",
    \"connector_type\": \"snowflake\",
    \"config\": {
      \"connection_string\": \"snowflake://ANALYTICS:$[e-mail]-central-1/SALES/PUBLIC?warehouse=COMPUTE_WH\"
    }
  }"

Capture the returned id for the steps that follow:

export CONNECTOR_ID="$CONNECTOR_ID"

Expected result: a 201 response with the connector id, "connector_type": "snowflake", and "status": "untested". Credentials are encrypted at rest — the connector object never returns your config back to you, only its name, type, status, and last test result.

The structured form requires account, user, password, and database together; if any is missing and no connection_string is given, the engine returns 422 missing_connection_string. Provide a real warehouse — a role with no warehouse access surfaces a clear error at test time.

4

Test the connection

POST /v1/connectors/{id}/test makes a real connection attempt — it logs in, activates the warehouse, and runs SELECT CURRENT_VERSION() — then flips the connector to live on success or error on failure. Browsing requires a live connector, so always test first.

curl -s -X POST "$ALGENTA_BASE_URL/v1/connectors/$CONNECTOR_ID/test" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"

Expected result: {"success": true, "status": "ok", "latency_ms": 312, "message": "Snowflake connection successful (xy12345.eu-central-1)"}, and the connector's stored status is now live. On failure, success is false; error_type plus recoverable tell you whether to fix credentials and retry. An error_type: "permission" with a privacy-policy message means the account host is outside your deployment's egress allowlist.

5

Browse the tables it exposes

GET /v1/connectors/{id}/browse lists the tables the live connector can see in its database and schema, so you can pick what to onboard. This returns 409 not_connected if the connector is not live — run the test step first.

curl -s "$ALGENTA_BASE_URL/v1/connectors/$CONNECTOR_ID/browse" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"

Expected result: a response with "connector_type": "snowflake", an items array (each entry is a browsable table), a total, a message, and discovery metadata. Note the name of the table you want to query — for example ORDERS.

6

Onboard one table as a dataset

POST /v1/data/connect ties the saved connector to a selection — a table or a SQL query — and registers the result as a queryable dataset. Reference the connector by connection_id, set connection_type to database and provider to snowflake, and name the table in selection.

curl -s -X POST "$ALGENTA_BASE_URL/v1/data/connect" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"connection_type\": \"database\",
    \"provider\": \"snowflake\",
    \"dataset_name\": \"sales_orders\",
    \"connection_id\": \"$CONNECTOR_ID\",
    \"selection\": {\"table\": \"PUBLIC.ORDERS\"},
    \"visibility\": \"private\"
  }"

To onboard a derived shape instead of a whole table, pass selection as a SQL query — for example {"sql_query": "SELECT region, amount FROM PUBLIC.ORDERS"}.

Expected result: when the selection identifies one table, "status": "ready" with a dataset_id, a schema_summary (row and column counts), and the connection_id. If the connection resolves to more than one table, you get "status": "needs_selection" with a choices array — re-call /v1/data/connect with the returned connection_id and one selection from choices. Save the dataset_id:

export DATASET_ID="$DATASET_ID"

7

Run a governed query

The table is now governed data. POST /v1/query runs a deterministic, typed query against the dataset and returns rows under the engine's validated contract.

curl -s -X POST "$ALGENTA_BASE_URL/v1/query" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"dataset_id\": \"$DATASET_ID\",
    \"select\": [\"region\", \"amount\"],
    \"limit\": 10
  }"

Expected result: a 200 response with the matching rows and the resolved query plan. Re-running the same request against the same dataset returns the same rows in the same order — governed queries are deterministic by design.

Expected result

You have a saved snowflake connector with status: "live", a browse listing of its tables, a dataset onboarded from one of them that appears in GET /v1/data with a dataset_id and a profiled schema, and a first query returning rows. The same intent against the same dataset returns the same deterministic answer, and every access is auditable.

Other ways to connect

The same endpoints back the de CLI and the Python SDK — all three hit the identical API.

de connectors create connector.json     # POST /v1/connectors from a JSON body
de connectors test $CONNECTOR_ID         # real connection health check
de connectors browse $CONNECTOR_ID       # browse the live connector's tables
de data connect connect.json             # POST /v1/data/connect from a JSON body
de data list                             # list registered datasets

import os
from decision_engine import AlgentaClient

client = AlgentaClient(
    api_key=os.environ["ALGENTA_API_KEY"],
    base_url="https://api.algenta.ai",
)

connector = client.create_connector(
    name="Analytics Warehouse",
    connector_type="snowflake",
    config={
        "account": "xy12345.eu-central-1",
        "user": "ANALYTICS",
        "password": os.environ["SNOWFLAKE_PASSWORD"],
        "warehouse": "COMPUTE_WH",
        "database": "SALES",
        "schema": "PUBLIC",
    },
)

test = client.test_connector(connector.id)
assert test.success, test.message

browse = client.browse_connector(connector.id)
print(browse.total, "tables")

result = client.connect_data(
    connection_type="database",
    provider="snowflake",
    dataset_name="sales_orders",
    connection_id=connector.id,
    selection={"table": "PUBLIC.ORDERS"},
    visibility="private",
)
print(result.status, result.dataset_id)

Troubleshooting

422 missing_connection_string. The structured form is incomplete. Supply account, user, password, and database together, or pass a single connection_string DSN instead.

409 not_connected when browsing. The connector is not live. Run POST /v1/connectors/{id}/test first; only a connector that passes its test can be browsed.

Test fails mentioning the warehouse is not accessible for the current role. Grant warehouse usage to the login's role, or use a login permitted for a role with access to the warehouse you set. See Authentication.

Test fails with error_type: "permission" or a privacy-policy message. The Snowflake account host is outside the egress allowlist for your deployment. Confirm the account value and that the destination is permitted by your deployment's egress policy. See Troubleshooting for the full diagnosis flow.

Next

Query governed dataMake your first queryBigQuery