Snowpark Container Services: Working with services¶
Snowpark Container Services enables you to easily deploy, manage, and scale containerized applications. After you create an application and upload the application image to a repository in your Snowflake account, you can run your application containers as a service.
A service represents Snowflake running your containerized application on a compute pool. There are two types of services:
long running services. A long-running is like a web service that does not end automatically. After you create a service, Snowflake manages the running service. For example, if a service container stops, for whatever reason, Snowflake restarts that container so the service runs uninterrupted.
job services. A job service terminates when your code exits, similar to a stored procedure. When all containers exit, the job service is done.
If your service needs more resources, such as more compute power, Snowflake provisions additional nodes in the compute pool.
Snowpark Container Services provides a set of SQL commands you can use to create and manage a service. These include:
Creating a service. CREATE SERVICE, EXECUTE JOB SERVICE
Altering a service. ALTER SERVICE, DROP SERVICE
Getting information about a service. SHOW SERVICES, DESCRIBE SERVICE
Starting Services¶
The minimum information required to start a service includes:
A name: Name of the service.
A service specification: This specification provides Snowflake with the information needed to run your service. The specification is a YAML file.
A compute pool: Snowflake runs your service in the specified compute pool.
Create a long running service¶
Use CREATE SERVICE to create a long running service.
Create a service using an inline specification. In most cases, during development, you might choose inline specification, as shown:
CREATE SERVICE echo_service IN COMPUTE POOL tutorial_compute_pool FROM SPECIFICATION $$ spec: containers: - name: echo image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:tutorial readinessProbe: port: 8000 path: /healthcheck endpoints: - name: echoendpoint port: 8000 public: true $$;
Create a service using stage information. When you deploy the service in a production environment, it’s advisable to apply the separation of concerns design principle and upload the specification to a stage, provide stage information CREATE SERVICE command, as shown:
CREATE SERVICE echo_service IN COMPUTE POOL tutorial_compute_pool FROM @tutorial_stage SPECIFICATION_FILE='echo_spec.yaml';
Execute a job service¶
Use EXECUTE JOB SERVICE to create a job service. This command runs synchronously, returns response after all containers of the job service exit.
Execute a job service using an inline specification:
EXECUTE JOB SERVICE IN COMPUTE POOL tutorial_compute_pool NAME = example_job_service FROM SPECIFICATION $$ spec: container: - name: main image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest env: SNOWFLAKE_WAREHOUSE: tutorial_warehouse args: - "--query=select current_time() as time,'hello'" - "--result_table=results" $$;
Execute a job service using stage information:
EXECUTE JOB SERVICE IN COMPUTE POOL tutorial_compute_pool NAME = example_job_service FROM @tutorial_stage SPECIFICATION_FILE='my_job_spec.yaml';
Create multiple service instances and configure autoscaling¶
By default, Snowflake runs one instance of the service in the specified compute pool. To manage heavy workloads, you can run multiple service instances by setting the MIN_INSTANCES and MAX_INSTANCES properties, which specify the minimum number of instances of the service to start with and the maximum instances Snowflake can scale to when needed.
Note
A job service can have only one instance running.
Example
CREATE SERVICE echo_service
IN COMPUTE POOL tutorial_compute_pool
FROM @tutorial_stage
SPECIFICATION_FILE='echo_spec.yaml'
MIN_INSTANCES=2
MAX_INSTANCES=4;
When multiple service instances are running, Snowflake automatically provides a load balancer to distribute the incoming requests.
To configure Snowflake to autoscale the number of service instances running, follow these steps:
Specify the memory and CPU requirements for your service instance in the service specification file. For more information, see the container.resources field.
Example
resources: requests: memory: <memory-reserved> cpu: <cpu-units>
When running the CREATE SERVICE command, set the MIN_INSTANCES and MAX_INSTANCES parameters. You can also use ALTER SERVICE to change these values.
Snowflake starts by creating the minimum number of service instances on the specified compute pool and then automatically scales the number of instances as needed. Snowflake uses an 80% threshold (for both CPU and memory) to scale up or scale down the number of service instances.
At any given time, one or more service instances can be running on the specified compute pool. Snowflake continuously monitors resource utilization (memory or CPU) within the compute pool, aggregating the usage data from all currently running service instances.
When the aggregated resource usage (across all service instances) surpasses 80%, Snowflake deploys an additional service instance within the compute pool. If the aggregated resource usage falls below 80%, Snowflake scales down by removing a running service instance. Snowflake uses a five-minute stabilization window to prevent frequent scaling.
Note the following scaling behaviors:
The scaling of service instances is constrained by the MIN_INSTANCES and MAX_INSTANCES parameters configured for the service.
If scaling up is necessary and the compute pool nodes lack the necessary resource capacity to start up another service instance, compute pool autoscaling can be triggered. For more information, see Autoscaling of compute pool nodes.
If you specify the MAX_INSTANCES and MIN_INSTANCES parameters when creating a service but don’t specify the memory and CPU requirements for your service instance in the service specification file, no autoscaling occurs; Snowflake starts with the number of instances specified by the MIN_INSTANCES property and will not autoscale.
Modifying and dropping services¶
After creating a service, you can use DROP SERVICE to remove a service from a schema (Snowflake terminates all the service containers).
You can also use the ALTER SERVICE command to modify the service. For example, suspend or resume the service, change the number of instances running, and direct Snowflake to redeploy your service using a new service specification.
Note
You cannot alter a job service.
Updating service code redeploying the service¶
You can modify your application code and configuration, and provide a new service specification in a ALTER SERVICE command to direct Snowflake to redeploy your running service using the new specification.
You first upload modified application code to your image repository and then call ALTER SERVICE providing the service specification either inline or specifying the path to a specification file in Snowflake stage. For example:
Provide specification inline (partial specification is shown).
ALTER SERVICE echo_service FROM SPECIFICATION $$ spec: … … $$;
Provide Snowflake stage file path:
ALTER SERVICE echo_service FROM @tutorial_stage SPECIFICATION_FILE='echo_spec.yaml';
Upon receiving the request, Snowflake redeploys the service using the new code.
ALTER SERVICE always uses the most recent version of the image from your repository. For example, if you upload multiple versions of an image named “echo_service:latest” or “echo_service:sometag”, Snowflake will use the latest uploaded image version.
You can use the DESCRIBE SERVICE command to find the image version the service is running. If you are the service owner, DESCRIBE SERVICE output includes the service specification, where you get the image digest (SHA256 of the image). For example:
spec:
containers:
- name: "echo"
image: "orgname-acctname.registry-dev.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest"
sha256: "@sha256:8d912284f935ecf6c4753f42016777e09e3893eed61218b2960f782ef2b367af"
env:
SERVER_PORT: "8000"
CHARACTER_NAME: "Bob"
readinessProbe:
port: 8000
path: "/healthcheck"
endpoints:
- name: "echoendpoint"
port: 8000
public: true
Note
If you suspend and resume a service, Snowflake deploys the same image version; it is not a service update operation.
You can update code of a service but not a job service.
Get information about services¶
You can use DESCRIBE SERVICE get properties of a service (including a job service). You can also use SHOW SERVICES to list current services (including job services) in the current database and schema for which you have permissions. You can also add filters to scope the SHOW SERVICES output:
Constrain output by SQL context (account, database, or schema) of the object: For example, use the IN ACCOUNT filter to list services in your Snowflake account, regardless of which database or schema the services belong to. This is useful if you have Snowflake services created in multiple databases and schemas in your account. Like all other commands, SHOW SERVICES IN ACCOUNTS is gated by privileges, returning only the services for which the role you are using has viewing permissions.
You can also specify IN DATABASE or IN SCHEMA to list the services in the current (or specified) database or schema.
Constrain output by the compute poo:l For example, use IN COMPUTE POOL filter to list the services running in a compute pool.
Constrain output by service name pattern: You can apply the LIKE and STARTS WITH filters to filter the services by name.
Constrain output to return only or excluding job service: You can use SHOW JOB SERVICES or SHOW SERVICES EXCLUDE JOBS to list only job services or exclude job services.
You can also combine these options to customize the SHOW SERVICES output.
Monitoring a service¶
Use SYSTEM$GET_SERVICE_STATUS to get the detailed runtime status of a service or a job service. For example, you can call this function to determine whether the service is still running or whether the service failed to start. If the service failed to start, the function provides more details about the failure.
When calling this function, pass in the name of the service.
Example
CALL SYSTEM$GET_SERVICE_STATUS('echo_service');
The following are example outputs:
Sample output of a service that is running one instance and has one container:
[ { "status":"READY", "message":"Running", "containerName":"echo", "instanceId":"0", "serviceName":"ECHO_SERVICE", "image":"<account>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:tutorial", "restartCount":0, "startTime":"2023-01-01T00:00:00Z" } ]
instanceId
is the service instance ID to which the container belongs. If you run two instances of this service, the output includes two such objects and provides the container status for each service instance. In this case, the instance IDs are 0 and 1.Note that the preceding output is formatted for convenience. You can use the PARSE_JSON function to get formatted output of SYSTEM$GET_SERVICE_STATUS.
SELECT PARSE_JSON(SYSTEM$GET_SERVICE_STATUS('echo_service'));
Sample output of a service that is running one instance and has three containers:
[ { "status":"READY", "message":"Running", "containerName":"some-proxy", "instanceId":"0", "serviceName":"EXAMPLE_SERVICE", "image":"<account>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_service_image_proxy:tutorial", "restartCount":0, "startTime":"2023-01-01T00:00:00Z" }, { "status":"READY", "message":"Running", "containerName":"some-server", "instanceId":"0", "serviceName":"EXAMPLE_SERVICE", "image":"<account>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_server:tutorial", "restartCount":0, "startTime":"2023-01-01T00:00:00Z" }, { "status":"READY", "message":"Running", "containerName":"movies", "instanceId":"0", "serviceName":"EXAMPLE_SERVICE", "image":"<account>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_movies:tutorial", "restartCount":0, "startTime":"2023-01-01T00:00:00Z" } ]
The output includes status information for each container. All these containers belong to the single service instance that has the instance ID 0.
SYSTEM$GET_SERVICE_STATUS takes an optional timeout_secs
argument. If timeout_secs
is not specified or is specified with value 0, the function immediately returns the current status. If timeout_secs
is specified, Snowflake waits until the service reaches a terminal state (READY or FAILED) within the specified time before returning the service status. If the service does not reach the terminal state within the specified time, Snowflake returns the current state at the end of the specified time interval.
The timeout you specify is an approximation based on when you expect the service to be ready, and this can help identify situations such as when Snowflake is waiting for other services and jobs to stop and free up resources in the specified compute pool before starting another service. The following SYSTEM$GET_SERVICE_STATUS function specifies a 10-second timeout:
call SYSTEM$GET_SERVICE_STATUS('echo_service', 10);
Accessing local container logs¶
Snowflake collects whatever your application container outputs to standard output or standard errors. You should ensure that your code outputs useful information to debug a service.
Snowflake provides two ways to access these service (including job service) container logs:
Using the SYSTEM$GET_SERVICE_LOGS system function: Gives access to logs from a specific container. After a container exits, you can continue to access the logs using the system function for a short time. System functions are most useful during development and testing, when you are initially authoring a service or a job. For more information, see SYSTEM$GET_SERVICE_LOGS.
Using an event table: An event table gives you access to logs from multiple containers across all services. Snowflake persists the logs in the event table for later access. Event tables are best used for the retrospective analysis of services and jobs. For more information, see Using an event table.
Using SYSTEM$GET_SERVICE_LOGS¶
You provide the service name, instance ID, container name, and optionally the number of most recent log lines to retrieve. If only one service instance is running, the service instance ID is 0. For example, the following GET_SERVICE_LOGS command retrieves the
trailing 10 lines from the log of a container named echo
that belongs to instance 0 of a service named echo_service
:
CALL SYSTEM$GET_SERVICE_LOGS('echo_service', '0', 'echo', 10);
If you don’t know service information (such as the instance ID or container name), you can first run GET_SERVICE_STATUS to get information about the service instances and containers running in each instance.
Example output:
+--------------------------------------------------------------------------+
| SYSTEM$GET_SERVICE_LOGS |
|--------------------------------------------------------------------------|
| 10.16.6.163 - - [11/Apr/2023 21:44:03] "GET /healthcheck HTTP/1.1" 200 - |
| 10.16.6.163 - - [11/Apr/2023 21:44:08] "GET /healthcheck HTTP/1.1" 200 - |
| 10.16.6.163 - - [11/Apr/2023 21:44:13] "GET /healthcheck HTTP/1.1" 200 - |
| 10.16.6.163 - - [11/Apr/2023 21:44:18] "GET /healthcheck HTTP/1.1" 200 - |
+--------------------------------------------------------------------------+
1 Row(s) produced. Time Elapsed: 0.878s
SYSTEM$GET_SERVICE_LOGS output has the following limitations:
It simply merges standard output and standard error streams, which makes it impossible to distinguish between regular output and error messages.
It reports the captured data for a specific container in a single service instance.
It only reports logs for a running container. The function cannot fetch logs from a previous container that was restarted or from a container of a service that is stopped or deleted.
The function returns up to 100 KB of data.
Using an event table¶
Snowflake can capture and record standard output and standard errors from your containers into the event table configured for your account. For more information, see Logging and Tracing Overview.
For example, the following SELECT query retrieves Snowflake service and job events recorded in the past hour:
SELECT TIMESTAMP, RESOURCE_ATTRIBUTES, RECORD_ATTRIBUTES, VALUE
FROM <current-event-table-for-your-account>
WHERE timestamp > dateadd(hour, -1, current_timestamp())
AND RESOURCE_ATTRIBUTES:"snow.executable.type" = 'SnowparkContainers'
ORDER BY timestamp DESC
LIMIT 10;
Snowflake recommends that you include a timestamp in the WHERE clause of event table queries, as shown in this example. This is particularly important because of the potential volume of data generated by various Snowflake components. By applying filters, you can retrieve a smaller subset of data, which improves query performance.
You control the level of logs (all, errors only, or none) that you want persisted in an event table by using the spec.logExporters field in the service specification file.
The events table includes the following columns, which provide useful information regarding the logs collected by Snowflake from your container:
TIMESTAMP: Shows when Snowflake collected the log.
RESOURCE_ATTRIBUTES: Each object in this column identifies which Snowflake service and container in the service generated the log. For example, it furnishes details such as the service name, container name, and compute pool name that were specified when the service was run.
{ "snow.containers.compute_pool.id": 549816068, "snow.containers.compute_pool.name": "TUTORIAL_COMPUTE_POOL", "snow.containers.container.name": "echo", "snow.containers.instance.name": "0", "snow.containers.restart.id": "cd0cf2", "snow.database.id": 549816076, "snow.database.name": "TUTORIAL_DB", "snow.executable.id": 980991015, "snow.executable.name": "ECHO_SERVICE", "snow.executable.type": "SnowparkContainers", "snow.schema.id": 549816076, "snow.schema.name": "DATA_SCHEMA" }
RECORD_ATTRIBUTES: For a Snowflake service, it identifies an error source (standard output or standard error).
{ "log.iostream": "stdout" }
VALUE: Standard output and standard error are broken into lines, and each line generates a record in the event table.
"echo-service [2023-10-23 17:52:27,429] [DEBUG] Sending response: {'data': [[0, 'Joe said hello!']]}"
Configuring an event table¶
For more information, see Logging and Tracing Overview.
Accessing compute pool metrics¶
Your services run on a Snowflake compute pool you provide. Each compute pool publishes a set of metrics about the nodes in the compute pool (for example, the amount of free memory available for use by containers on a node) and the containers running in that compute pool (for example, memory used by a specific container).
You can use the published metrics to understand where in the compute pool your service is running and what resources your service is using. For more information, see Compute Pool Metrics.
Managing access to service endpoints¶
Caution
In production, you grant a role the USAGE privilege on a service by using the GRANT <privileges> command:
GRANT USAGE ON SERVICE <service_name> TO ROLE <role_name>
However, if the 2024_04 behavior change bundle is enabled for your account, the preceding GRANT command will not work. Instead of granting service-level privileges, you must now grant roles privileges on specific service endpoints. You use the concept of service roles to manage endpoint-level privileges as explained in this section.
The service owner role (the role that you use to create the service) has full access to the service and endpoints the service exposes. Other roles will need USAGE privilege on the endpoints to communicate with the service. For example,
The owner role of the client needs USAGE privilege on the endpoint. Client refers to a service function or a service making requests to endpoints of another service.
To create a service function referencing an endpoint, the user needs access to the endpoint. That is, the service function’s owner role needs USAGE privilege on the endpoint referenced in the CREATE FUNCTION.
In service-to-service communications, the owner role of the client service (that is calling the other service’s endpoint) needs the USAGE privilege on the endpoint.
A user making ingress requests from outside Snowflake to a public endpoint needs USAGE privilege on the endpoint.
Ability to grant other roles privileges on service endpoints is a two-step process:
Define one or more service roles in the service specification. Within the definition, indicate the endpoints for which the role holds the USAGE privilege.
After creating the service, use these commands to grant (or revoke) the service roles to other roles: GRANT SERVICE ROLE, REVOKE SERVICE ROLE. You can also use these commands to display information about the grants: SHOW ROLES IN SERVICE, SHOW GRANTS.
Snowflake creates the service roles when you create a service and deletes them when you delete the service. Snowflake also defines a default service role (ALL_ENDPOINTS_USAGE
) that grants USAGE privilege on all endpoints the service exposes and grants this default service role to the service owner role. Thus, the owner role can access all the endpoints the service exposes. If you use the same role to create multiple services, because the owner role has access to all endpoints, those services can communicate with each other seamlessly without extra configuration.
Note that if a service has multiple containers, they can communicate with each other via localhost, and these communications are local within each service instance and not subject to role-based access control.
The following sections provide details. You can also try a tutorial (Configure and test service endpoint privileges) that provides step-by-step instructions to explore this feature.
Prerequisite to use this feature¶
To manage endpoint access using a service role, you must enable the 2024_04 behavior change bundle in your account.
To enable this bundle in your account, execute the following statement:
SELECT SYSTEM$ENABLE_BEHAVIOR_CHANGE_BUNDLE('2024_04');
To help you adopt these changes, Snowflake has already created the default service role (ALL_ENDPOINTS_USAGE) for each of your existing services. Snowflake also has granted the default service role to other roles that you previously granted USAGE privilege on that service, so the existing services should work seamlessly.
However, some issue might prevent Snowflake from creating the default service role. You can run the following SHOW ROLES IN SERVICE command to verify the default service role is created for your service.
SHOW ROLES IN SERVICE <service_name>;
Example output:
+-------------------------------+-------------------------+------------+
| created_on | name | comment |
+-------------------------------+-------------------------+------------+
| 2024-04-29 14:58:50.063 -0700 | ALL_ENDPOINTS_USAGE | |
+-------------------------------+-------------------------+------------+
Check the output; if the output contains the default service role (ALL_ENDPOINTS_USAGE), no further action is needed. Otherwise, do the following to create the default service role and grant it to other roles:
Run the ALTER SERVICE command to upgrade the service …
ALTER SERVICE <name> { FROM @<stage> SPECIFICATION_FILE = '<yaml_file_stage_path>' | FROM SPECIFICATION <specification_text> }
Use the GRANT SERVICE ROLE command to grant the default service role (
ALL_ENDPOINTS_USAGE
) to roles that you previously granted USAGE privilege on the service.GRANT SERVICE ROLE <service-name>!ALL_ENDPOINTS_USAGE TO ROLE <another_role>;
Granting the USAGE privilege on all endpoints¶
When you create a service (including job service), Snowflake also creates a default service role, named ALL_ENDPOINTS_USAGE
. This role has USAGE privilege on all endpoints the service exposes. You can grant other roles this default service role using the GRANT SERVICE ROLE command:
GRANT SERVICE ROLE my_echo_service_image!ALL_ENDPOINTS_USAGE TO ROLE some_other_role;
Users who are using some_other_role
have the USAGE privilege on all the service endpoints.
When you drop a service, Snowflake drops all the service roles (default service role and service roles defined in the service specification) associated with the service and voids all the service role grants.
Granting the USAGE privilege to specific endpoints¶
Use service roles to manage fine-grained access to service endpoints. You define the service roles, along with the list of endpoints they are granted USAGE privilege to, in the service specification.
Granting privilege on specific endpoints of a service is a two-step process:
Define a service role: Use a service specification to define a service role by providing a role name and a list of one or more endpoints for which you want to grant USAGE privilege. For example, in the following specification fragment, the top-level
serviceRoles
field defines two service roles, each with USAGE privilege on specific endpoints.spec: ... serviceRoles: # Optional list of service roles - name: <svc_role_name1> endpoints: # endpoints that role can access - <endpoint_name1> - <endpoint_name2> - name: <svc_role_name2> endpoints: - <endpoint_name3> - <endpoint_name4>
Grant the service role to other roles. Using the GRANT SERVICE ROLE command, you grant the service role to other roles (account roles, application roles, or database roles). For example:
GRANT SERVICE ROLE <service-name>!<svc_role_name1> TO ROLE <another-role>
Using a service¶
After creating a service, you can use any of the following three supported methods to communicate with it:
Service function: Create a service function (UDF) that is associated with the service. Then, use the service function to communicate with a service from a SQL query. You can associate a service function only with HTTP or HTTPS endpoints. For an example, see Tutorial 1.
Ingress: Use public endpoints that are exposed by the service to access the service from outside Snowflake. In this case, Snowflake manages access control. Ingress is allowed only with HTTP or HTTPS endpoints. For an example, see Tutorial 1.
Service-to-service communications: Use a Snowflake-assigned service DNS name for service-to-service communication. If an endpoint is created only to allow service-to-service communications, TCP protocol should be used. For an example, see Tutorial 3.
Note
Both service function and ingress are not supported with job service. A job service runs like a job and terminates when done. A service function is not needed to communicate with it and therefore associating a service function with a job service is not supported. Also, a job service does not support ingress. That is, EXECUTE JOB SERVICE will fail if the spec file includes a public endpoint.
Service-to-service communications is not supported when destination of the communications is a job service.
The following sections provide details.
Service functions: Using a service from an SQL query¶
A service function is a user-defined function (UDF) you
create using CREATE FUNCTION. However, instead of writing
the UDF code directly, you associate the UDF with your
service. For example, in Tutorial 1, you create a
service named echo_service
that exposes one endpoint (echoendoint) as defined in the service specification:
spec:
…
endpoints:
- name: echoendpoint
port: 8080
echoendpoint
is a user-friendly endpoint name that represents the
corresponding port (8080). To communicate with this service endpoint, you create
a service function by providing the SERVICE and ENDPOINT parameters as shown:
CREATE FUNCTION my_echo_udf (text varchar)
RETURNS varchar
SERVICE=echo_service
ENDPOINT=echoendpoint
AS '/echo';
The AS
parameter provides the HTTP path to the service code.
You get this path value from the service code
(for example, see service.py in Tutorial 1).
@app.post("/echo")
def echo():
...
When you invoke the service function, Snowflake directs the request to the associated service endpoint and path.
Note
A service function is used to communicate with a service, and not with a job. In other words, you can only associate a service (not a job) with a service function.
When you run multiple instances of your service, you can create a service function
by specifying the optional MAX_BATCH_ROWS
parameter
to limit the
batch size, the maximum rows that Snowflake sends in a batch to
the service. For example, suppose MAX_BATCH_ROWS
is 10 and you call
my_echo_udf
service function with 100 input rows. Snowflake
partitions the input rows into batches, with each batch having at most 10 rows,
and sends a series of requests to the service with the batch of rows in the
request body. Configuring batch size can help when processing takes nontrivial time, and
distributing rows across all available servers can also help.
You can use ALTER FUNCTION to alter a service function. The following ALTER FUNCTION command changes the service endpoint to which it associates and the batch size:
ALTER FUNCTION my_echo_udf(VARCHAR)
SET SERVICE=other_service
ENDPOINT=otherendpoint
MAX_BATCH_ROWS=100
Data exchange format¶
For data exchange between a service function and a container,
Snowflake follows the same format that external functions
use (see Data Formats).
For example, suppose you have data rows stored in a table (input_table
):
"Alex", "2014-01-01 16:00:00"
"Steve", "2015-01-01 16:00:00"
…
To send this data to your service, you invoke the service function by passing these rows as parameters:
SELECT service_func(col1, col2) FROM input_table;
Snowflake sends a series of requests to the container, with batches of data rows in the request body in this format:
{
"data":[
[
0,
"Alex",
"2014-01-01 16:00:00"
],
[
1,
"Steve",
"2015-01-01 16:00:00"
],
…
[
<row_index>,
"<column1>",
"<column2>"
],
]
}
The container then returns the output in the following format:
{
"data":[
[0, "a"],
[1, "b"],
…
[ row_index, output_column1]
]
}
The example output shown assumes that the result is a one-column table with rows (“a”, “b” …).
When multiple service instances are running, you can create a service
function using the MAX_BATCH_ROWS
parameter to distribute the input
rows for processing across all available servers.
Privileges required to create and manage service functions¶
To create and manage service functions, a role needs the following privileges:
To create a service function: The current role must have the USAGE privilege on the service being referenced.
To alter a service function: You can alter a service function and associate it with another service. The current role must have the USAGE privilege on the new service.
To use a service function: The current role must have the USAGE privilege on the service function, and the service function owner role must have the USAGE privilege on the associated service.
The following example script shows how you might grant permission to use a service function:
USE ROLE service_owner;
GRANT USAGE ON service service_db.my_schema.my_service TO ROLE func_owner;
USE ROLE func_owner;
CREATE OR REPLACE test_udf(v VARCHAR)
RETURNS VARCHAR
SERVICE=service_db.my_schema.my_service
ENDPOINT=endpointname1
AS '/run';
SELECT test_udf(col1) FROM some_table;
ALTER FUNCTION test_udf(VARCHAR) SET
SERVICE = service_db.other_schema.other_service
ENDPOINT=anotherendpoint;
GRANT USAGE ON FUNCTION test_udf(varchar) TO ROLE func_user;
USE ROLE func_user;
SELECT my_test_udf('abcd');
Ingress: Using a service from outside Snowflake¶
A service can expose one or more endpoints as public to allow users to use the service from the public web.
Note
For Public Private Preview, the ACCOUNTADMIN of your Snowflake account must execute the following command:
CREATE SECURITY INTEGRATION SNOWSERVICES_INGRESS_OAUTH
TYPE=oauth
OAUTH_CLIENT=snowservices_ingress
ENABLED=true;
Mark the endpoint as public in your service specification file:
spec
...
endpoints
- name: <endpoint name>
port: <port number>
public: true
For more information about service specifications, see Specification Reference.
Public endpoint access and authentication¶
Snowpark Container Services requires Snowflake OAuth to authenticate requests to public endpoints. For example, you will be required to sign in using username and password. Behind the scenes, your sign-in generates an OAuth token from Snowflake. The OAuth token is then used to send a request to the service endpoint.
Note
Not everyone can access the public endpoints exposed by a service. Only users in the same Snowflake account having a role with the USAGE privilege on a service can access the public endpoints of the service.
You can access the public endpoint using a browser or programmatically:
Accessing a public endpoint by using a browser: When a browser is used to access a public endpoint, there is an automatic redirect for user authentication. You can explore Tutorial 1 to test this experience.
Accessing a public endpoint programmatically: The following Python example code uses the Snowflake Connector for Python to first generate a session token that represents your identity. The code then uses the session token to log in to the public endpoint.
import snowflake.connector import requests ctx = snowflake.connector.connect( user="<username>",# username password="<password>", # insert password here account="<orgname>-<acct-name>", session_parameters={ 'PYTHON_CONNECTOR_QUERY_RESULT_FORMAT': 'json' }) # Obtain a session token. token_data = ctx._rest._token_request('ISSUE') token_extract = token_data['data']['sessionToken'] # Create a request to the ingress endpoint with authz. token = f'\"{token_extract}\"' headers = {'Authorization': f'Snowflake Token={token}'} # Set this to the ingress endpoint URL for your service url = 'http://<ingress_url>' # Validate the connection. response = requests.get(f'{url}', headers=headers) print(response.text) # Insert your code to interact with the application here
In the code:
If you don’t know your account information (
<orgname>-<acctname>
), see the Tutorial common setup.You can get the
ingress_url
of the public endpoint exposed by the service by using SHOW ENDPOINTS.
User-specific headers in ingress requests¶
When a request for an ingress endpoint arrives, Snowflake automatically passes the following headers along with the HTTP request to the container.
Sf-Context-Current-User: <user_name> Sf-Context-Current-User-Email: <email>
You container code can optionally read these headers, know who the caller is, and apply context-specific customization for different users.
Service-to-service communications¶
Services can communicate with each other using the DNS name that Snowflake automatically assigns to each service. For an example, see Tutorial 3.
The DNS name format is:
<service-name>.<schema-name>.<db-name>.snowflakecomputing.internal
Use SHOW SERVICES (or DESCRIBE SERVICE) to get the DNS name of a service.
The preceding DNS name is a full name. Services created in the same schema can
communicate using just the <service-name>
. Services that are in the same database
but different schemas must provide the schema name, such as <service-name>.<schema-name>
.
Snowflake allows network communications between services created by the same role and blocks network communications between services created by different roles. If you want to prevent your services from communicating with each other (for reasons such as security), use different Snowflake roles to create those services.
DNS names have the following limitations:
Your database, schema, or service names must be valid DNS labels. (See also https://www.ietf.org/rfc/rfc1035.html#section-2.3.1). Otherwise, creating a service will fail.
Snowflake replaces an underscore (_) in the names (database, schema, and service name) by a dash (-) in the DNS name.
After creating a service, do not change the database or the schema name, because Snowflake will not update the DNS name of the service.
A DNS name is only for internal communications within Snowflake between services running in the same account. It is not accessible from the internet.
Privileges¶
Privilege |
Usage |
Notes |
---|---|---|
USAGE |
To communicate with a service you need the USAGE privilege on the service endpoint. Required for creating a service function, using public endpoints, and connecting from another service. |
|
MONITOR |
To monitor a service and get runtime status. |
|
OPERATE |
To suspend or resume a service. |
|
OWNERSHIP |
Full control over the service. Only a single role can hold this privilege on a specific object at a time. |
|
ALL [ PRIVILEGES ] |
Grants all privileges, except OWNERSHIP, on the service. |