Gemini & Snowflake Integration - Complete Package

Executive Summary

This package contains a fully functional application that bridges Google Gemini (AI) with Snowflake (Data Warehouse). It allows non-technical users to ask business questions in plain English and receive accurate data results instantly.

Key Features:

• Natural Language Processing: Converts English questions to Snowflake SQL.
• Safety Layer: Validates SQL to prevent destructive commands (DROP, DELETE).
• Context Awareness: Uses a YAML semantic model from Solid to understand specific business logic and table relationships.
• Web Interface: A user-friendly dashboard for asking questions and viewing tabular results.

---

Quick Start Guide

Prerequisites

• Python 3.8 or higher
• A Snowflake Account
• A Google Gemini API Key (AI Studio)

Installation Commands

Create Project & Environment

mkdir gemini-snowflake-app
cd gemini-snowflake-app
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Install Dependencies

pip install -r requirements.txt

Configure Environment

Create a .env file and add your API keys. See The .env File section below for the complete format.

Run Application

python -m app.main

Access the interface at: http://localhost:8000

---

Complete Setup Guide

Step 1: Project Structure

Ensure your folders look exactly like this:

gemini-snowflake-app/
├── app/
│   ├── __init__.py          # Empty file
│   ├── config.py            # Environment config
│   ├── gemini_client.py     # AI logic
│   ├── main.py              # Server entry point
│   ├── semantic_model.py    # YAML loader
│   ├── snowflake_client.py  # Database connection
│   ├── sql_validator.py     # Safety checks
│   └── formatter.py         # Result formatting
├── static/
│   └── index.html           # Web interface
├── .env                     # Secrets (API Keys)
├── model.yaml               # Your database schema definitions
└── requirements.txt         # Python libraries

Step 2: Install Python Dependencies

Create a virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Step 3: Create Configuration File

⚠️ SECURITY WARNING: Never commit your .env file to Git!

Create a .env file in the project root with your credentials. This file is automatically excluded from Git via .gitignore. See The .env File section below for the complete format.

Step 4: Download Semantic Model

You must download your semantic model YAML file from SOLID before running the application.

1. Access SOLID Platform: Log into your SOLID account
2. Navigate to Semantic Models: Go to the semantic models section in SOLID
3. Download Your Model: Download the YAML file for your specific semantic model
4. Place in Project Root: Save the downloaded YAML file as model.yaml in the project root directory
5. Update Configuration: Ensure SEMANTIC_MODEL_PATH in your .env file matches the filename (default: model.yaml)

Important: The semantic model YAML file defines your database schema, tables, columns, relationships, and metrics. This file is required for the AI to understand your data structure and generate accurate SQL queries.

---

Configuration & Semantic Model

The .env File {#the-env-file}

🔒 SECURITY: Never commit .env files to Git!

Create a file named .env in the root directory. Do not share this file or commit it to version control.

The .gitignore file is configured to automatically exclude .env files from Git.

GEMINI_API_KEY=your_gemini_api_key_here
SNOWFLAKE_ACCOUNT=xy12345.us-east-1
SNOWFLAKE_USER=my_user
SNOWFLAKE_PASSWORD=my_password
SNOWFLAKE_WAREHOUSE=COMPUTE_WH
SNOWFLAKE_DATABASE=SALES_DB
SNOWFLAKE_SCHEMA=PUBLIC
SEMANTIC_MODEL_PATH=model.yaml

The Semantic Model (model.yaml)

This is the "Brain" of the system. The semantic model YAML file defines how the AI understands your database structure.

Where to Get It

1. Log into SOLID Platform
2. Navigate to Semantic Models: Find the semantic models section in your SOLID dashboard
3. Select Your Model: Choose the semantic model that matches your database schema
4. Download: Download the YAML file for your semantic model
5. Save as model.yaml: Place the downloaded file in your project root directory

What It Contains

The YAML file defines:

• Tables: All database tables and their physical names
• Columns: Column names, types, and descriptions
• Relationships: How tables join together
• Metrics: Pre-defined calculations and formulas
• Synonyms: Business-friendly terms that map to technical names

Example Structure

tables:
  - name: ORDERS
    description: Customer transactions
    columns:
      - name: ORDER_ID
        type: VARCHAR
      - name: AMOUNT
        type: DECIMAL

Note: Your actual YAML file from SOLID will be much more comprehensive and include all your tables, relationships, and business context.

---

Usage Examples

API Usage

Ask a Question:

curl -X POST "http://localhost:8000/api/ask" \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the total revenue?"}'

Web Interface

1. Open http://localhost:8000
2. Type your question
3. Click "Ask AI"

---

License

MIT