> This page is for Structured Data Models Client.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/sdgm/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/sdgm/_mcp/server.

# Snowflake

> Deploy Kumo Tabular NIM containers on Snowpark Container Services.

Deploy Kumo Tabular NIM as a Snowpark Container
Services (SPCS) service. This recipe copies a published NIM image to a Snowflake
image repository and runs one model on one GPU per service instance. The service
exposes the NIM HTTP API for classification and regression.

Replace each `<...>` placeholder with a value for your environment. Run SQL
statements with a Snowflake role that has the required privileges. Run the Bash
commands in the same terminal so that the image variables remain available.

## Before you start

* A Snowflake account with SPCS available and a GPU compute pool compatible
  with the selected NIM profile. Use `SHOW COMPUTE POOL INSTANCE FAMILIES` to
  check the available instance families and their resource capacity.
* A database and schema where you can create an image repository and service.
  The service owner needs `USAGE` on the compute pool and `READ` on the image
  repository. A public endpoint also requires `BIND SERVICE ENDPOINT` on the
  account. See [CREATE SERVICE](https://docs.snowflake.com/en/sql-reference/sql/create-service)
  for privileges, including access to the parent database and schema.
* A Bash shell, Docker, and a configured
  [Snowflake CLI connection](https://docs.snowflake.com/en/developer-guide/snowflake-cli/index).
* Access to the selected release of the
  [Kumo Tabular NIM image](https://catalog.ngc.nvidia.com/orgs/nim/nvidia/containers/kumo-tabular).
  Follow NGC's authentication instructions for your account.

## 1. Create Snowflake resources

Use an existing GPU compute pool or create one using an available GPU instance
family compatible with the model profile:

```sql
SHOW COMPUTE POOL INSTANCE FAMILIES;

CREATE COMPUTE POOL <compute_pool>
  MIN_NODES = 1
  MAX_NODES = 1
  INSTANCE_FAMILY = <gpu_instance_family>
  AUTO_RESUME = TRUE;
```

Create an image repository in an existing database and schema:

```sql
CREATE IMAGE REPOSITORY IF NOT EXISTS <database>.<schema>.<repository>;

SHOW IMAGE REPOSITORIES IN SCHEMA <database>.<schema>;
```

Copy `repository_url` from the output. It has the form
`<registry-host>/<database>/<schema>/<repository>`. See Snowflake's
[image repository guide](https://docs.snowflake.com/en/developer-guide/snowpark-container-services/working-with-registry-repository)
for repository privileges and URL details.

## 2. Pull the NIM image from NVIDIA

Set `NIM_VERSION` to a published Kumo Tabular image tag. If the image requires
NGC authentication, log in with an NGC API key that can access it:

```bash
read -r -s -p 'NGC API key: ' NGC_API_KEY
printf '\n'
printf '%s' "$NGC_API_KEY" | docker login nvcr.io \
  --username '$oauthtoken' --password-stdin
unset NGC_API_KEY

NIM_VERSION='<published-tag>'
NVIDIA_IMAGE="nvcr.io/nim/nvidia/kumo-tabular:${NIM_VERSION}"
docker pull "$NVIDIA_IMAGE"
```

Use an image architecture compatible with the selected Snowflake compute pool.
The packaged NIM contains its model artifacts, so it does not need to download
the model at service startup. See the
[Kumo Tabular NIM catalog](https://catalog.ngc.nvidia.com/orgs/nim/nvidia/containers/kumo-tabular)
for release details.

## 3. Push the image to Snowflake

Log Docker in to the Snowflake image registry using your configured CLI
connection. Set `SNOWFLAKE_REPOSITORY_URL` to the `repository_url` from step 1,
without a trailing slash:

```bash
snow spcs image-registry login --connection <connection_name>

SNOWFLAKE_REPOSITORY_URL='<repository_url>'
SNOWFLAKE_IMAGE="${SNOWFLAKE_REPOSITORY_URL}/kumo-tabular:${NIM_VERSION}"
docker tag "$NVIDIA_IMAGE" "$SNOWFLAKE_IMAGE"
docker push "$SNOWFLAKE_IMAGE"
```

Confirm that the image is available and record its tag and digest:

```sql
SHOW IMAGES IN IMAGE REPOSITORY <database>.<schema>.<repository>;
```

The [Snowflake CLI registry login reference](https://docs.snowflake.com/en/developer-guide/snowflake-cli/command-reference/spcs-commands/image-registry-commands/login)
describes connection options and authentication requirements.

## 4. Start the service

Create a service with one instance using the inline specification below. Replace
`<nim_version>` with the tag you pushed in step 3. SQL
does not substitute the Bash variables from the previous steps. The image path
begins with `/` and omits the registry hostname.

```sql
CREATE SERVICE <database>.<schema>.<service>
  IN COMPUTE POOL <compute_pool>
  FROM SPECIFICATION $$
spec:
  containers:
    - name: nim
      image: /<database>/<schema>/<repository>/kumo-tabular:<nim_version>
      mountSessionToken: false
      env:
        NIM_HTTP_API_PORT: "8000"
      resources:
        requests:
          cpu: 4
          memory: 24Gi
          nvidia.com/gpu: 1
        limits:
          nvidia.com/gpu: 1
      readinessProbe:
        port: 8000
        path: /v1/health/ready
  endpoints:
    - name: inference
      port: 8000
      protocol: HTTP
      public: true
  $$
  MIN_INSTANCES = 1
  MAX_INSTANCES = 1
  AUTO_RESUME = TRUE;
```

The CPU and memory requests are starting values. Verify the selected model
profile's requirements and the compute pool's available resources.

This specification exposes a public endpoint. For clients connecting only from
SPCS, set `public: false` to keep the endpoint private. A private endpoint does
not require the account privilege for binding a public service endpoint.

Check the service and its endpoint while the container starts:

```sql
SELECT SYSTEM$GET_SERVICE_STATUS('<database>.<schema>.<service>');
SHOW SERVICE CONTAINERS IN SERVICE <database>.<schema>.<service>;
SHOW ENDPOINTS IN SERVICE <database>.<schema>.<service>;
```

Wait until the NIM container is ready. The readiness probe calls
`/v1/health/ready`, which becomes ready after the model loads. If startup fails,
review the container status and the
[Snowflake service monitoring guidance](https://docs.snowflake.com/en/developer-guide/snowpark-container-services/monitoring-services)
before retrying.

## 5. Access the NIM endpoint

### From a Snowflake notebook using Container Runtime

For a notebook running on an SPCS compute pool, use the service's internal DNS
name and port. Obtain `dns_name` from `DESCRIBE SERVICE` and the port from
`SHOW ENDPOINTS`:

```sql
DESCRIBE SERVICE <database>.<schema>.<service>;
SHOW ENDPOINTS IN SERVICE <database>.<schema>.<service>;
```

In a notebook Python cell with `requests` installed, verify readiness and list
the available models. Replace `<service_dns_name>` with the returned DNS name.
The example service uses port `8000`:

```python
import requests

nim_endpoint = "http://<service_dns_name>:8000"
response = requests.get(f"{nim_endpoint}/v1/health/ready", timeout=30)
response.raise_for_status()

response = requests.get(f"{nim_endpoint}/v1/models", timeout=30)
response.raise_for_status()
response.json()
```

This route uses internal networking without a public ingress URL or token.
Services with the same owner role can access each other's endpoints. When the
owner roles differ, the client service's owner role needs the destination
service role. See Snowflake's
[service-to-service access rules](https://docs.snowflake.com/en/developer-guide/snowpark-container-services/working-with-services#service-to-service-communications).
If access is denied, confirm the notebook's Container Runtime identity and its
grants. Warehouse Runtime notebooks use different networking; this internal DNS
example applies to Container Runtime.

## 6. Manage the service

When the service is no longer needed, suspend it:

```sql
ALTER SERVICE <database>.<schema>.<service> SUSPEND;
```

Resume it when needed:

```sql
ALTER SERVICE <database>.<schema>.<service> RESUME;
```

NIM sessions reside in process memory and must be recreated after a restart or
suspension. Keep one service instance for session-based requests unless your
deployment provides routing that keeps each session on its originating instance.
Suspending the service does not suspend other services or delete the compute
pool and image repository. Review the compute pool's suspension settings when
the deployment is no longer in use.