> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snowflake Tools

> Manage stages, run Snowpark Python, and use Cortex search to power advanced data workflows in Snowflake.

## **Overview**

### **Tool Name**

```json theme={null}
snowflake_tools
```

### **Purpose**

The **snowflake\_tools** suite gives you Snowflake-specific power that goes beyond standard SQL. Work with stages and files, run Python in Snowpark, and use Cortex search to retrieve AI-ranked results from indexed content.

### **Key Features & Functions**

<Steps>
  <Step title="Stage Operations" icon="box-open">
    List, upload, read, and delete files in Snowflake stages to support file-based pipelines.
  </Step>

  <Step title="Snowpark Python" icon="python">
    Execute Python against Snowflake data for analytics, data science, and ML.
  </Step>

  <Step title="Cortex Search" icon="snowflake">
    Run AI-powered search over configured services to surface relevant content quickly.
  </Step>

  <Step title="Artifacts" icon="file">
    Persist outputs and files as artifacts for easy sharing and traceability.
  </Step>
</Steps>

<Tip>
  Unless your workflow specifies otherwise, use your **WORKSPACE** database, schema, and stage to simplify file paths and permissions.
</Tip>

## **Input Parameters for Each Function**

### **`_list_stage_contents`**

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **database** | Target database name. | String |
| **schema** | Target schema name. | String |
| **stage** | Stage name to inspect. | String |
| **pattern** | Filename or glob-style pattern to filter results. | String |

### **`_add_file_to_stage`**

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **database** | Database that owns the stage. | String |
| **schema** | Schema that owns the stage. | String |
| **stage** | Stage name. | String |
| **file\_name** | Full local path to the file to upload. | String |
| **target\_path** | Optional subfolder on the stage, exclude the filename. | String |

### **`_delete_file_from_stage`**

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **database** | Database that owns the stage. | String |
| **schema** | Schema that owns the stage. | String |
| **stage** | Stage name. | String |
| **file\_name** | Original filename on the stage, with optional path. | String |

### **`_read_file_from_stage`**

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **database** | Database that owns the stage. | String |
| **schema** | Schema that owns the stage. | String |
| **stage** | Stage name. | String |
| **file\_name** | Filename on the stage, with optional path. | String |
| **return\_contents** | Return file contents instead of only the filename. | Boolean |
| **is\_binary** | Treat file as binary when returning contents. | Boolean |
| **max\_bytes** | Maximum bytes to return when streaming content. Default 10000. | Integer |
| **save\_artifacts** | Save the downloaded file as an artifact with a link for reuse and sharing. | Boolean |

<Note>
  For binary reads, set `is_binary = true`. If you also set `save_artifacts = true`, the file will be persisted and returned with an artifact link.
</Note>

### **`_cortex_search`**

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **service\_name** | Name of the configured Cortex search service. | String |
| **query** | Short text query to search for. | String |
| **top\_n** | Number of top results to return. Default 15, max 25. | Integer |

### **`_run_snowpark_python`**

<Note>
  When an administrator has hidden the virtual System `Snowflake` connection and
  a Snowpark call resolves to `connection_id="Snowflake"`, Genesis returns
  `success: false` with `type: connection_disabled` before opening the session.
  Pass an explicit user-created Snowflake connection id when the built-in
  connection is hidden.

  On SQLite-metadata deployments (`SNOWFLAKE_METADATA=FALSE`), stage and Snowpark
  entry points that resolve the default `connection_id="Snowflake"` return
  `success: false` with `error_code: STAGE_REQUIRES_SNOWFLAKE_CONNECTION` before
  opening a session. Pass a user-created saved Snowflake connection id, or use
  `execute_python_code(executor="local")` when Snowflake is not configured.
</Note>

**Parameters**

| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **code** | Python code to execute in Snowpark. | String |
| **purpose** | Human-readable explanation used for validation and auditing. | String |
| **packages** | Comma-separated list of additional packages to install. | String |
| **additional\_imports** | Optional list of additional Python helper files for multi-file Snowpark runs. For `source="inline"`, Genesis stages only these helper files and keeps the main script embedded. Missing or out-of-root helper paths fail before execution. | Array\[String] |
| **note\_id** | Execute previously saved code by note id instead of passing `code`. | String |
| **save\_artifacts** | Persist outputs as artifacts for later access and sharing. | Boolean |

<Note>
  For multi-file inline runs, pass helper modules in `additional_imports`, such
  as `["helper.py"]` or `["pkg/helper.py"]`. Genesis stages those helper files
  for Snowpark imports without converting the main inline script into a staged
  module.
</Note>

## **Use Cases**

1. Create data visualizations from Snowflake data with matplotlib or similar libraries.
2. Perform advanced statistical analysis on enterprise datasets.
3. Build and run machine learning models inside Snowflake.
4. Process CSVs by uploading to stages and analyzing with Snowpark.
5. Generate automated reports and dashboards with Python-based workflows.
6. Search indexed documentation and knowledge bases using Cortex AI.
7. Spin up temporary data workflows that leverage Snowflake compute.
8. Develop custom transformation scripts for large-scale datasets.
9. Combine SQL and Python for interactive analysis.
10. Manage file-based pipelines for ETL and data quality validation.

## **Workflow/How It Works**

1. **Land files** with `_add_file_to_stage` or verify with `_list_stage_contents`.
2. **Transform and analyze** using `_run_snowpark_python` with access to Snowflake data.
3. **Discover content** via `_cortex_search` for AI-ranked retrieval when needed.
4. **Retrieve or share** with `_read_file_from_stage`, optionally saving results as artifacts.

## **Integration Relevance**

* **data\_connector\_tools** for SQL-centric operations that complement Snowpark workloads.
* **file\_manager\_tools** to register outputs and maintain lineage.
* **artifact\_manager\_tools** to persist visualizations, CSVs, or notebooks.
* **project\_manager\_tools** to track Snowflake tasks across missions and todos.
* **image\_tools** to inspect or analyze images generated by Snowpark code.

<Warning>
  Snowpark jobs and frequent stage operations can incur compute and storage costs. Ensure roles, warehouses, and stage privileges are configured before running workloads.
</Warning>

## **Configuration Details**

* Use forward slashes in stage paths and avoid special characters.
* Ensure your role has `USAGE` on the database and schema, plus required privileges on the stage.
* When stage creation fails because the Snowflake session has no current database, Genesis returns `error_code: CONNECTION_DATABASE_UNAVAILABLE` naming the connection's configured database and schema. Fix those fields in **Config → Connections**, grant the role `USAGE` on the database, or pass a different `connection_id`.
* In Snowpark, set a top-level `result` variable in your code to capture returned output.
* Cortex services must be provisioned and indexed before you can query them.
* Package names should exclude standard libraries and list only additional needs.

## **Limitations or Notes**

1. Stage and Snowpark operations require appropriate Snowflake permissions.
2. Large files and long-running Python jobs may hit resource or timeout limits.
3. First-time package installation in Snowpark can add latency.
4. Cortex search availability depends on account features and service configuration.
5. Complex Python tasks can require significant compute and time.
6. Binary file handling may require `is_binary = true` and `max_bytes` tuning.
7. Network connectivity to Snowflake is required for all operations.
8. `_sync_git_to_stage` never uploads `.git` metadata. `exclude_git_metadata` defaults to `true`; passing `false` is refused. Clone or push the repository to share its Git history.

## **Output**

* **Stage Operations**
  Listings, upload confirmations, deletions, and resolved file paths.
* **File Content**
  Returned text or binary bytes with size and encoding info when requested.
* **Cortex Search**
  Ranked results with relevance scores and snippets.
* **Snowpark Execution**
  Captured `result`, console logs, and optional artifacts for downstream use.
* **Artifacts**
  Artifact ids and links for reports, images, or data files created during execution.
* **Errors**
  Clear messages for permission issues, invalid paths, missing services, or runtime failures.