> For the complete documentation index, see [llms.txt](https://docs.espresso.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.espresso.ai/snowflake-optimizer/nitro-spcs-onboarding.md).

# Nitro query execution

Run the SQL below as `ACCOUNTADMIN`. Grant source-table access to `NITRO` and grant that role to your existing Espresso role. Espresso inherits that access and manages the Nitro runtime through its existing login.

## 1. Select the existing role and warehouse

Use the existing Espresso role and warehouse. Set the maximum nodes per pool to the capacity agreed with Espresso.

```sql
USE ROLE ACCOUNTADMIN;
SET ESPRESSO_ROLE = 'REPLACE_WITH_EXISTING_ESPRESSO_ROLE';
SET NITRO_WAREHOUSE = 'REPLACE_WITH_EXISTING_WAREHOUSE';
SET NITRO_MAX_NODES = 4;
USE WAREHOUSE IDENTIFIER($NITRO_WAREHOUSE);
```

## 2. Create the Nitro role and runtime resources

```sql
CREATE ROLE NITRO;
GRANT ROLE NITRO TO ROLE SYSADMIN;
GRANT ROLE NITRO TO ROLE IDENTIFIER($ESPRESSO_ROLE);

CREATE DATABASE ESPRESS_NITRO;
GRANT OWNERSHIP ON DATABASE ESPRESS_NITRO TO ROLE NITRO COPY CURRENT GRANTS;

EXECUTE IMMEDIATE $$
DECLARE
    families RESULTSET;
    pool_name VARCHAR;
    statement VARCHAR;
    max_nodes INTEGER DEFAULT $NITRO_MAX_NODES;
BEGIN
    families := (EXECUTE IMMEDIATE 'SHOW COMPUTE POOL INSTANCE FAMILIES');
    FOR family IN families DO
        IF (family."message" ILIKE '%reservation only%') THEN
            CONTINUE;
        END IF;
        pool_name := 'ESPRESS_NITRO_' || family."name";
        statement := 'CREATE COMPUTE POOL ' || pool_name
            || ' MIN_NODES = 1 MAX_NODES = ' || max_nodes
            || ' INSTANCE_FAMILY = ' || family."name"
            || ' INITIALLY_SUSPENDED = TRUE AUTO_RESUME = TRUE AUTO_SUSPEND_SECS = 60';
        EXECUTE IMMEDIATE :statement;
        statement := 'GRANT OWNERSHIP ON COMPUTE POOL ' || pool_name
            || ' TO ROLE NITRO COPY CURRENT GRANTS';
        EXECUTE IMMEDIATE :statement;
    END FOR;
END;
$$;

GRANT USAGE ON WAREHOUSE IDENTIFIER($NITRO_WAREHOUSE) TO ROLE NITRO;
GRANT USAGE ON WAREHOUSE IDENTIFIER($NITRO_WAREHOUSE)
    TO ROLE IDENTIFIER($ESPRESSO_ROLE);

USE ROLE NITRO;
USE SECONDARY ROLES NONE;
CREATE SCHEMA ESPRESS_NITRO.ARTIFACTS;
CREATE SCHEMA ESPRESS_NITRO.RUNTIME;
CREATE IMAGE REPOSITORY ESPRESS_NITRO.ARTIFACTS.IMAGES;
CREATE STAGE ESPRESS_NITRO.RUNTIME.SCRATCH
    ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');
USE ROLE ACCOUNTADMIN;

GRANT USAGE ON DATABASE ESPRESS_NITRO TO ROLE PUBLIC;
GRANT USAGE ON SCHEMA ESPRESS_NITRO.RUNTIME TO ROLE PUBLIC;
```

## 3. Grant source-table access

Grant `NITRO` access to the tables or views Nitro will process, using your existing access policies. Repeat for each source. For a view, use `ON VIEW` in the `SELECT` grant.

```sql
GRANT USAGE ON DATABASE <source_database> TO ROLE NITRO;
GRANT USAGE ON SCHEMA <source_database>.<source_schema> TO ROLE NITRO;
GRANT SELECT ON TABLE <source_database>.<source_schema>.<source_table> TO ROLE NITRO;
```

## 4. Configure runtime access

These rules allow Nitro to download executables from Espresso's `apricot-snowflake-unload` bucket in `us-east-1` and read authorized input data from Snowflake's query-result storage in your account's region. Query output stays in Snowflake's internal stage.

```sql
USE ROLE ACCOUNTADMIN;
GRANT EXECUTE TASK ON ACCOUNT TO ROLE NITRO;

CREATE NETWORK RULE ESPRESS_NITRO.RUNTIME.BINARY_ACCESS
    MODE = EGRESS TYPE = HOST_PORT
    VALUE_LIST = (
        'apricot-snowflake-unload.s3.amazonaws.com:443',
        'apricot-snowflake-unload.s3.us-east-1.amazonaws.com:443',
        's3.us-east-1.amazonaws.com:443'
    );

EXECUTE IMMEDIATE $$
DECLARE
    hosts VARCHAR;
    statement VARCHAR;
BEGIN
    SELECT LISTAGG(DISTINCT '''' || REPLACE(value:host::VARCHAR, '''', '''''')
        || ':443''', ',') INTO :hosts
    FROM TABLE(FLATTEN(INPUT => PARSE_JSON(SYSTEM$ALLOWLIST())))
    WHERE value:type::VARCHAR = 'STAGE';

    statement := 'CREATE NETWORK RULE ESPRESS_NITRO.RUNTIME.STAGED_RESULT_ACCESS '
        || 'MODE = EGRESS TYPE = HOST_PORT VALUE_LIST = (' || hosts || ')';
    EXECUTE IMMEDIATE :statement;
END;
$$;

CREATE EXTERNAL ACCESS INTEGRATION ESPRESS_NITRO_ACCESS
    ALLOWED_NETWORK_RULES = (
        ESPRESS_NITRO.RUNTIME.BINARY_ACCESS,
        ESPRESS_NITRO.RUNTIME.STAGED_RESULT_ACCESS
    )
    ENABLED = TRUE;
GRANT USAGE ON INTEGRATION ESPRESS_NITRO_ACCESS TO ROLE NITRO;
```

Application users keep their existing warehouse and source-table permissions; do not grant `NITRO` to application roles.
