Snowflake REST API

Embucket implements the Snowflake REST API v1, providing compatibility with Snowflake clients and drivers. This API handles authentication, query execution, and session management.

Base URL

http(s)://host:port/

Example:

http://localhost:3000/

Authentication

All endpoints except login require authentication via JWT token in the Authorization header. Authenticate and obtain a session token. Query Parameters:

databaseName

string

Initial database to connect to.

schemaName

string

Initial schema to use.

warehouse

string

Warehouse identifier (accepted for compatibility).

Request Body:

{
  "data": {
    "CLIENT_APP_ID": "SnowflakeConnector",
    "CLIENT_APP_VERSION": "1.0.0",
    "SVN_REVISION": null,
    "ACCOUNT_NAME": "embucket",
    "LOGIN_NAME": "embucket",
    "PASSWORD": "embucket",
    "CLIENT_ENVIRONMENT": {
      "APPLICATION": "PythonConnector",
      "OS": "Linux",
      "OS_VERSION": "5.15.0"
    },
    "SESSION_PARAMETERS": {
      "QUERY_TAG": "analytics"
    }
  }
}

Request Fields:

data.CLIENT_APP_ID

string

required

Client application identifier.

data.CLIENT_APP_VERSION

string

required

Client application version.

data.SVN_REVISION

string

Optional SVN revision.

data.ACCOUNT_NAME

string

required

Account name for authentication.

Username for authentication.

data.PASSWORD

string

required

Password for authentication.

data.CLIENT_ENVIRONMENT

object

Client environment metadata (key-value pairs).

data.SESSION_PARAMETERS

object

Session parameters (key-value pairs).

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": null
}

success

boolean

Whether the login was successful.

data.token

string

JWT token for authenticated requests.

message

string

Error message if login failed.

Example:

curl -X POST http://localhost:3000/session/v1/login-request \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "CLIENT_APP_ID": "MyApp",
      "CLIENT_APP_VERSION": "1.0",
      "ACCOUNT_NAME": "embucket",
      "LOGIN_NAME": "embucket",
      "PASSWORD": "embucket",
      "CLIENT_ENVIRONMENT": {},
      "SESSION_PARAMETERS": {}
    }
  }'

Query Execution

POST /queries/v1/query-request

Execute a SQL query. Authentication: Required (JWT token) Query Parameters:

requestId

uuid

required

Unique identifier for this query request.

retryCount

integer

Number of retry attempts (for client retry logic).

Request Body:

{
  "sqlText": "SELECT * FROM my_table LIMIT 10",
  "asyncExec": false,
  "querySubmissionTime": 1678901234567
}

sqlText

string

required

SQL statement to execute.

asyncExec

boolean

Whether to execute asynchronously (not fully supported).

querySubmissionTime

integer

Client-side submission timestamp in milliseconds.

Response (Success):

{
  "success": true,
  "data": {
    "rowtype": [
      {
        "name": "id",
        "database": "analytics",
        "schema": "public",
        "table": "my_table",
        "nullable": false,
        "type": "INTEGER",
        "byteLength": null,
        "length": null,
        "scale": null,
        "precision": null,
        "collation": null
      }
    ],
    "rowset": [
      [1],
      [2],
      [3]
    ],
    "total": 3,
    "returned": 3,
    "queryResultFormat": "json",
    "queryId": "01928374-5647-8abc-def0-123456789abc"
  },
  "message": null,
  "code": null
}

Response Fields:

data.rowtype

array

Array of column metadata objects.

data.rowtype[].name

string

Column name.

data.rowtype[].type

string

Column data type (INTEGER, VARCHAR, TIMESTAMP, etc.).

data.rowtype[].nullable

boolean

Whether the column accepts NULL values.

data.rowtype[].database

string

Database name.

data.rowtype[].schema

string

Schema name.

data.rowtype[].table

string

Table name.

data.rowset

array

Array of result rows. Each row is an array of values.

data.total

integer

Total number of rows in the result set.

data.returned

integer

Number of rows returned in this response.

data.queryResultFormat

string

Format of the result data (“json” or “arrow”).

data.queryId

string

Unique identifier for the executed query.

Response (Error):

{
  "success": false,
  "data": {
    "errorCode": "002003",
    "sqlState": "42S02",
    "queryId": "01928374-5647-8abc-def0-123456789abc"
  },
  "message": "Table 'my_table' does not exist",
  "code": "002003"
}

data.errorCode

string

Snowflake-compatible error code.

data.sqlState

string

SQL state code.

message

string

Human-readable error message.

Example:

curl -X POST "http://localhost:3000/queries/v1/query-request?requestId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "sqlText": "SELECT * FROM my_table LIMIT 10",
    "asyncExec": false
  }'

POST /queries/v1/abort-request

Abort a running query. Authentication: Required (JWT token) Request Body:

{
  "sqlText": "SELECT * FROM long_running_query",
  "requestId": "123e4567-e89b-12d3-a456-426614174000"
}

sqlText

string

required

SQL text of the query to abort.

requestId

uuid

required

Request ID of the query to abort.

Response:

null

Returns null on success. Example:

curl -X POST http://localhost:3000/queries/v1/abort-request \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "sqlText": "SELECT * FROM long_query",
    "requestId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Session Management

POST /session

Manage or delete a session. Authentication: Required (JWT token) Query Parameters:

delete

boolean

default:"false"

Whether to delete the session.

requestId

string

Optional request identifier.

request_guid

string

Optional request GUID.

Response:

null

Returns null on success. Example (Delete Session):

curl -X POST "http://localhost:3000/session?delete=true" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Utility Endpoints

GET /health

Health check endpoint for monitoring and load balancers. Authentication: Not required Response:

"OK"

Returns a simple “OK” string when the service is healthy. Example:

curl http://localhost:3000/health

Use Case: This endpoint is typically used for:

Kubernetes liveness/readiness probes
Load balancer health checks
Monitoring systems
Service discovery

POST /telemetry/send

Telemetry endpoint for client-side metrics (Snowflake client compatibility). Authentication: Not required Request Body: Accepts telemetry data from Snowflake clients. Response:

"OK"

Returns “OK” after receiving telemetry data. Embucket accepts but does not process client telemetry. Example:

curl -X POST http://localhost:3000/telemetry/send \
  -H "Content-Type: application/json" \
  -d '{"events": []}'

Error Codes

Embucket returns Snowflake-compatible error codes:

Code	SQL State	Description
002003	42S02	Table does not exist
002043	42710	Object already exists
090106	22000	Invalid data format
100132	22007	Date/time parsing error
000606	57014	Query execution aborted

Request Headers

Authentication Header

All authenticated endpoints require:

Authorization: Bearer <jwt_token>

Content Type

All requests should use:

Content-Type: application/json

Compression

The API supports request and response compression:

Accept-Encoding: gzip
Content-Encoding: gzip

Rate Limiting

Rate limiting is controlled by the --max-concurrency-level flag:

embucketd --max-concurrency-level 32

When the limit is reached, new queries will queue until slots become available.

Data Formats

The API supports multiple data serialization formats:

JSON (Default)

Results returned as nested JSON arrays:

{
  "data": {
    "rowset": [
      [1, "Alice"],
      [2, "Bob"]
    ]
  }
}

Arrow (Base64)

Results can be returned as Base64-encoded Apache Arrow:

{
  "data": {
    "rowsetBase64": "QVJST1cxAA==",
    "queryResultFormat": "arrow"
  }
}

Configure via:

embucketd --data-format arrow

Example Integration

Python Client

import requests
import uuid

class EmbucketClient:
    def __init__(self, host, port, user, password):
        self.base_url = f"http://{host}:{port}"
        self.token = None
        self._login(user, password)
    
    def _login(self, user, password):
        response = requests.post(
            f"{self.base_url}/session/v1/login-request",
            json={
                "data": {
                    "CLIENT_APP_ID": "PythonClient",
                    "CLIENT_APP_VERSION": "1.0",
                    "ACCOUNT_NAME": "embucket",
                    "LOGIN_NAME": user,
                    "PASSWORD": password,
                    "CLIENT_ENVIRONMENT": {},
                    "SESSION_PARAMETERS": {}
                }
            }
        )
        response.raise_for_status()
        self.token = response.json()["data"]["token"]
    
    def execute(self, sql):
        request_id = str(uuid.uuid4())
        response = requests.post(
            f"{self.base_url}/queries/v1/query-request",
            params={"requestId": request_id},
            headers={"Authorization": f"Bearer {self.token}"},
            json={"sqlText": sql, "asyncExec": False}
        )
        response.raise_for_status()
        return response.json()

# Usage
client = EmbucketClient("localhost", 3000, "embucket", "embucket")
result = client.execute("SELECT * FROM my_table LIMIT 10")
print(result["data"]["rowset"])

CLI

Configuration

REST API

Documentation Index

​Base URL

​Authentication

​POST /session/v1/login-request

​Query Execution

​POST /queries/v1/query-request

​POST /queries/v1/abort-request

​Session Management

​POST /session

​Utility Endpoints

​GET /health

​POST /telemetry/send

​Error Codes

​Request Headers

​Authentication Header

​Content Type

​Compression

​Rate Limiting

​Data Formats

​JSON (Default)

​Arrow (Base64)

​Example Integration

​Python Client

Base URL

Authentication

POST /session/v1/login-request

Query Execution

POST /queries/v1/query-request

POST /queries/v1/abort-request

Session Management

POST /session

Utility Endpoints

GET /health

POST /telemetry/send

Error Codes

Request Headers

Authentication Header

Content Type

Compression

Rate Limiting

Data Formats

JSON (Default)

Arrow (Base64)

Example Integration

Python Client