Skip to main content

​
Overview

​
Tool Name

​
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

Stage Operations

List, upload, read, and delete files in Snowflake stages to support file-based pipelines.

Snowpark Python

Execute Python against Snowflake data for analytics, data science, and ML.

Cortex Search

Run AI-powered search over configured services to surface relevant content quickly.

Artifacts

Persist outputs and files as artifacts for easy sharing and traceability.
Unless your workflow specifies otherwise, use your WORKSPACE database, schema, and stage to simplify file paths and permissions.

​
Input Parameters for Each Function

​
_list_stage_contents

Parameters

​
_add_file_to_stage

Parameters

​
_delete_file_from_stage

Parameters

​
_read_file_from_stage

Parameters
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.

​
_cortex_search

Parameters

​
_run_snowpark_python

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.
Parameters
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.

​
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.
Snowpark jobs and frequent stage operations can incur compute and storage costs. Ensure roles, warehouses, and stage privileges are configured before running workloads.

​
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.