### Start Spark Connect Server

Source: https://docs.getwren.ai/cp/guide/connect/spark

Use spark-submit to launch the Spark Connect server on your cluster. Ensure the package and JAR versions match your specific Spark installation.

```bash
spark-submit \

  --packages org.apache.spark:spark-connect_2.12:3.5.0 \

  --class org.apache.spark.sql.connect.service.SparkConnectServer \

  /usr/lib/spark/jars/spark-connect_2.12-3.5.0.jar
```

--------------------------------

### Install Wren CLI on Linux (ARM64)

Source: https://docs.getwren.ai/cp/guide/cli/cli-install-and-login

Downloads and installs the CLI binary for Linux ARM64 architectures.

```bash

curl -L https://assets.getwren.ai/wren_cli/latest/linux/wren-linux-arm64.tar.gz \

| tar -xz && sudo mv wren-linux-arm64 /usr/local/bin/wren && wren  


```

--------------------------------

### Install Wren CLI on Linux (x86_64)

Source: https://docs.getwren.ai/cp/guide/cli/cli-install-and-login

Downloads and installs the CLI binary for Linux x86_64 architectures.

```bash

curl -L https://assets.getwren.ai/wren_cli/latest/linux/wren-linux.tar.gz \

| tar -xz && sudo mv wren-linux /usr/local/bin/wren && wren  


```

--------------------------------

### Install Wren CLI on macOS (Intel)

Source: https://docs.getwren.ai/cp/guide/cli/cli-install-and-login

Downloads and installs the CLI binary for macOS Intel architectures.

```bash

curl -L https://assets.getwren.ai/wren_cli/latest/macos/wren-darwin.tar.gz \

| tar -xz && sudo mv wren-darwin /usr/local/bin/wren && wren  


```

--------------------------------

### Install Wren CLI on macOS (Apple Silicon)

Source: https://docs.getwren.ai/cp/guide/cli/cli-install-and-login

Downloads and installs the CLI binary for macOS Apple Silicon architectures.

```bash

curl -L https://assets.getwren.ai/wren_cli/latest/macos/wren-darwin-arm64.tar.gz \

| tar -xz && sudo mv wren-darwin-arm64 /usr/local/bin/wren && wren  


```

--------------------------------

### Example .wrenconfig file

Source: https://docs.getwren.ai/cp/guide/cli/cli-dbt

Configuration file structure for managing project ID and model sync filters.

```yaml
# .wrenconfig
wren_project:
  id: "783"
  last_synced: "2025-12-24T10:00:00Z"
  
filter:
  include:
    - "marts_.*"
    - "dim_.*"
  exclude:
    - ".*_test"
```

--------------------------------

### RBAC table schema and query examples

Source: https://docs.getwren.ai/cp/guide/security/rls-examples

Example schema and query transformation for role-based access control.

```sql
reports(  

  id INT,  

  report_name STRING,  

  required_role STRING  

)  
```

```sql
SELECT * FROM reports;  
```

```sql
SELECT * FROM reports  

WHERE required_role IN (SELECT value FROM SPLIT('FINANCE_ANALYST,HR_ADMIN', ','));  
```

--------------------------------

### Generate WrenAI MCP skill content locally

Source: https://docs.getwren.ai/cp/guide/integrations/wrenai-mcp

Use this command to clone the repository and run the setup script for the ChatGPT integration.

```bash
git clone https://github.com/canner/wrenai-mcp.git && cd wrenai-mcp && ./setup --host chatgpt
```

--------------------------------

### Entitlement mapping schema and query examples

Source: https://docs.getwren.ai/cp/guide/security/rls-examples

Schema and query examples for protected transactions using entitlement mapping.

```sql
transactions(  

  id         INT,  

  account_id STRING,  

  amount     NUMBER  

)  
```

```sql
SELECT * FROM transactions;  
```

```sql
SELECT * FROM transactions  

WHERE account_id IN (  

  SELECT account_entitlements.account_id  

  FROM account_entitlements  

  WHERE account_entitlements.customer_id = 'cust_123'  

);  
```

--------------------------------

### Example metadata YAML file

Source: https://docs.getwren.ai/cp/guide/cli/cli-metadata

Structure for individual table metadata files to be processed by the CLI.

```yaml
metadata:
  schema_name: test.customers
  purpose: Customer data table

columns:
  - name: customer_id
    type: string
    description: "Unique customer identifier."

  - name: customer_name
    type: string
    description: "Customer’s full name."

  - name: customer_address
    type: string
    description: "Customer address"
```

--------------------------------

### Define metadata configuration

Source: https://docs.getwren.ai/cp/guide/cli/cli-metadata

Example configuration file for mapping local YAML metadata to Wren AI project fields.

```yaml
# metadata-config.yaml

# Path or glob pattern to locate your metadata files.
# Can point to a single file, a directory, or use glob patterns.
file_path: "./metadata/*.yaml"

# (Optional) Limit included files when scanning a directory.
include_patterns:
  - "*.yaml"
  - "*.yml"

# (Optional) Exclude specific files or patterns.
exclude_patterns:
  - "*.backup.yaml"
  - "deprecated_*.yaml"

# Wren AI target project to sync with.
target_project_id: "123"

# Mapping rules for how metadata is extracted from YAML files.
description_property_name: "purpose"         # Field for table description
columns_property_name: "columns"             # Field listing columns
column_description_property_name: "description"  # Field for column descriptions

table_name_property: "metadata.schema_name"
```

--------------------------------

### Check Wren CLI Version

Source: https://docs.getwren.ai/cp/guide/cli/cli-install-and-login

Displays the currently installed version of the Wren CLI.

```bash

wren version  


```

--------------------------------

### Team Membership Queries

Source: https://docs.getwren.ai/cp/guide/security/rls-examples

Example of a standard query and the resulting compiled query with session properties applied.

```sql
SELECT * FROM tickets;  
```

```sql
SELECT * FROM tickets  

WHERE owner_user_id = 'u_42'  

   OR team_id IN (SELECT value FROM SPLIT('t1,t2', ','));  
```

--------------------------------

### Region Allow-list Queries

Source: https://docs.getwren.ai/cp/guide/security/rls-examples

Example of a standard query and the resulting compiled query with region session properties applied.

```sql
SELECT * FROM customers;  
```

```sql
SELECT * FROM customers  

WHERE region_id IN (SELECT value FROM SPLIT('US,CA', ','));  
```

--------------------------------

### API Response Example

Source: https://docs.getwren.ai/cp/guide/api-access/quick-start

The JSON structure returned by the generate_sql endpoint.

```json
{

  "id": "1fbc0d64-1c58-45b2-a990-9183bbbcf913",

  "sql": "SELECT * FROM \"olist_customers_dataset\"",

  "threadId": "9c537507-9cec-46ed-b877-07bfa6322bed"

}
```

--------------------------------

### Verify Wren CLI version

Source: https://docs.getwren.ai/cp/guide/cli/cli-dbt

Check the currently installed version of the Wren CLI.

```bash
wren version
```

--------------------------------

### RLS Policy Logic Example

Source: https://docs.getwren.ai/cp/guide/security/multi-tenancy

Demonstrates the logical filtering of data rows based on session properties.

```text
If session_property.organization_id = "wrenai"  

→ User can only access rows where organization_id = "wrenai"  
```

--------------------------------

### Standard TNS Descriptor

Source: https://docs.getwren.ai/cp/guide/connect/oracle

A full TNS descriptor example for a standard TCP connection.

```text
(DESCRIPTION =  
  (ADDRESS = (PROTOCOL = TCP)(HOST = your-hostname)(PORT = 1521))  
  (CONNECT_DATA =  
    (SERVICE_NAME = FREE)  
  )  
)
```

--------------------------------

### Create Wren project from dbt

Source: https://docs.getwren.ai/cp/guide/cli/cli-dbt

Initialize a new Wren AI project by importing your dbt models.

```bash
wren dbt create
```

--------------------------------

### Generate local skill files

Source: https://docs.getwren.ai/cp/guide/integrations/wrenai-mcp

Use this command to clone the repository and set up the local environment for generating skill files.

```bash
git clone https://github.com/canner/wrenai-mcp.git && cd wrenai-mcp && ./setup --host web
```

--------------------------------

### TNS Descriptor with SSL

Source: https://docs.getwren.ai/cp/guide/connect/oracle

A TNS descriptor example configured for a secure TCPS connection.

```text
(DESCRIPTION =  
  (ADDRESS = (PROTOCOL = TCPS)(HOST = db.example.com)(PORT = 2484))  
  (CONNECT_DATA =  
    (SERVICE_NAME = FREE)  
  )  
  (SECURITY =  
    (SSL_SERVER_CERT_DN = "CN=db.example.com,OU=DB,O=Example Corp,L=City,ST=State,C=US")  
  )  
)
```

--------------------------------

### Navigate to dbt project

Source: https://docs.getwren.ai/cp/guide/cli/cli-dbt

Change the working directory to your local dbt project path.

```bash
cd /path/to/your-dbt-project
```

--------------------------------

### Execute the backup script

Source: https://docs.getwren.ai/cp/backup_restore

Run the Python script to export current models and knowledge to the local filesystem.

```bash
python wren_backup.py   

```

--------------------------------

### Configure API access environment variables

Source: https://docs.getwren.ai/cp/backup_restore

Set the required API key and project ID as environment variables before running the backup script.

```bash
export WREN_API_KEY=your_api_key_here  

export WREN_PROJECT_ID=your_project_id  

```

--------------------------------

### Spot-check a sample table

Source: https://docs.getwren.ai/cp/guide/connect/clickhouse

Performs a sample read on a specific table to confirm that SELECT privileges are correctly applied to target objects.

```sql
-- Replace with one of the database/table pairs you intend to expose.  

SELECT *  

FROM analytics.orders  

LIMIT 1;  
```

--------------------------------

### Region Allow-list Table Schema

Source: https://docs.getwren.ai/cp/guide/security/rls-examples

Schema definition for the customers table used in the region allow-list example.

```sql
customers(  

  id INT,  

  name STRING,  

  region_id STRING  

)  
```

--------------------------------

### Team Membership Table Schema

Source: https://docs.getwren.ai/cp/guide/security/rls-examples

Schema definition for the tickets table used in the team membership example.

```sql
tickets(  

  id INT,  

  owner_user_id STRING,  

  team_id STRING,  

  subject STRING  

)  
```

--------------------------------

### Build dbt project

Source: https://docs.getwren.ai/cp/guide/cli/cli-dbt

Generate the manifest.json file required for Wren AI to understand your dbt resources.

```bash
dbt build
```

--------------------------------

### Raw SQL Query for Revenue

Source: https://docs.getwren.ai/cp/getting_started/best_practice

An example of a raw SQL query that is prone to errors due to missing business logic exclusions.

```sql
SELECT SUM(amount) AS revenue  

FROM payments  

WHERE paid_at >= '2025-10-01' AND paid_at < '2026-01-01'  

  AND status = 'paid';
```

--------------------------------

### Configure Chart Visualization Rules

Source: https://docs.getwren.ai/cp/guide/knowledge/instructions

Instruction to standardize the display format for 'top 5' comparison queries.

```text

When users ask for top 5 comparison, always return a horizontal bar chart sorted descending by value.  

The highest category should be highlighted in yellow.  


```

--------------------------------

### Generate dbt documentation

Source: https://docs.getwren.ai/cp/guide/cli/cli-dbt

Create the catalog.json file in the target directory to provide column type information.

```bash
dbt docs generate
```

--------------------------------

### Generate Signed JWT for Identity Verification

Source: https://docs.getwren.ai/cp/guide/integrations/embedded-threads

Use this Node.js backend example to sign a token with your Shared Secret Key, ensuring secure user identification.

```javascript
const express = require('express');  
const jwt = require('jsonwebtoken');  
const app = express();  
  
app.post('/signin', async (req, res) => {  
  try {  
    const user = await authenticateUser(req.body); // Your auth logic  
  
    // Get "Shared Secret Key" from Wren AI settings  
    const secret = process.env.WRENAI_EMBED_SECRET;  
  
    const payload = {  
      // Required: Unique identifier for the user (UUID format)  
      userId: user.id,  
      email: user.email,  
      name: user.name,  
      // Optional: RLS/CLS Session Properties  
      sessionProperties: [  
        { key: 'department', value: user.department }  
      ]  
    };  
  
    // Sign using the HS256 algorithm  
    const wrenaiToken = jwt.sign(payload, secret, { algorithm: 'HS256' });  
  
    res.json({ wrenaiToken });  
  } catch (error) {  
    res.status(500).json({ error: 'Internal server error' });  
  }  
});
```

--------------------------------

### Upgrade Wren CLI on Linux (ARM64)

Source: https://docs.getwren.ai/cp/guide/cli/cli-install-and-login

Downloads and replaces the existing CLI binary for Linux ARM64.

```bash

curl -L https://assets.getwren.ai/wren_cli/latest/linux/wren-linux-arm64.tar.gz \

| tar -xz && sudo mv wren-linux-arm64 /usr/local/bin/wren  


```

--------------------------------

### Configure Spark Connect Server EMR Step

Source: https://docs.getwren.ai/cp/guide/connect/emr-spark

Arguments required when adding a custom JAR step in the Amazon EMR Console to start the Spark Connect Server.

```bash
spark-submit --packages org.apache.spark:spark-connect_2.12:3.5.0 --class org.apache.spark.sql.connect.service.SparkConnectServer /usr/lib/spark/jars/spark-connect_2.12-3.5.0.jar
```

--------------------------------

### List Projects via cURL

Source: https://docs.getwren.ai/cp/guide/api-access/org-api-keys

Use the organization API key to list all projects within a specific organization.

```bash
curl -sS \
  -H "Authorization: Bearer $ORG_API_KEY" \
  https://api.getwren.ai/cloud/v1/projects?orgId={orgId}
```

--------------------------------

### Upgrade Wren CLI on Linux (x86_64)

Source: https://docs.getwren.ai/cp/guide/cli/cli-install-and-login

Downloads and replaces the existing CLI binary for Linux x86_64.

```bash

curl -L https://assets.getwren.ai/wren_cli/latest/linux/wren-linux.tar.gz \

| tar -xz && sudo mv wren-linux /usr/local/bin/wren  


```

--------------------------------

### Verify Connection and Version Access

Source: https://docs.getwren.ai/cp/guide/connect/mysql

Confirms the account can successfully connect to the server and retrieve the version information.

```sql
-- Confirms the account can connect and read the server version.  

SELECT VERSION();  
```

--------------------------------

### Verify SQL Server account permissions

Source: https://docs.getwren.ai/cp/guide/connect/sqlserver

Execute these queries to confirm the new user can access the necessary tables and metadata.

```sql
SELECT TABLE_SCHEMA, TABLE_NAME  

FROM INFORMATION_SCHEMA.TABLES  

WHERE TABLE_TYPE IN ('BASE TABLE', 'VIEW');  

  

SELECT TOP 5 * FROM dbo.your_table;
```

--------------------------------

### Verify Backup Directory Structure

Source: https://docs.getwren.ai/cp/backup_restore

The expected directory structure for the backup files.

```text
backup/  

├── models/  

├── instructions/  

├── sql_pairs
```

--------------------------------

### Preview update with filters

Source: https://docs.getwren.ai/cp/guide/cli/cli-dbt

Perform a dry-run update using specific filters without modifying the .wrenconfig file.

```bash
wren dbt update --dbt-path /path/to/dbt-project --include "orders" --dry-run
```

--------------------------------

### Authenticate with Wren AI Cloud

Source: https://docs.getwren.ai/cp/guide/cli/cli-install-and-login

Initiates the login process to authenticate the CLI against Wren AI Cloud.

```bash

wren auth login  


```

--------------------------------

### Verify Login and Version Access

Source: https://docs.getwren.ai/cp/guide/connect/oracle

Checks if the user can access the V$VERSION view, which is required for initial connection.

```sql
-- Connects and reads V$VERSION — exactly what Wren AI does on first connection.  

SELECT * FROM V$VERSION;
```

--------------------------------

### Execute Restore Script

Source: https://docs.getwren.ai/cp/backup_restore

Command to run the restore script.

```bash
python wren_restore.py
```

--------------------------------

### Handle Resource Synchronization and Deletions

Source: https://docs.getwren.ai/cp/backup_restore

Logic for updating existing resources, creating new ones, and deleting items on the server that are not present in the local backup.

```python
f"{list_url}/{item_id}", headers=headers, json=payload  

                ).raise_for_status()  

                processed_server_ids.add(item_id)  

            except Exception as e:  

                print(f"   ❌ Update failed: {e}")  

        else:  

            # Case: CREATE  

            # Either 'id' is missing (New Item) OR 'id' exists in backup but not on Server (Restore deleted item)  

            # Note: Server will assign a new ID.  

            if item_id:  

                print(f"➕ Creating {name} (Restoring missing ID: {item_id})")  

            else:  

                print(f"➕ Creating {name} (New Item)")  

  

            try:  

                requests.post(  

                    list_url, headers=headers, json=payload  

                ).raise_for_status()  

            except Exception as e:  

                print(f"   ❌ Create failed: {e}")  

  

    # 4. Process Deletions (Delete items on server not present in backup)  

    for item_id in current_map:  

        if item_id not in processed_server_ids:  

            print(f"🗑️ Deleting {name} ID: {item_id} (Not in backup)")  

            try:  

                requests.delete(  

                    f"{list_url}/{item_id}", headers=headers  

                ).raise_for_status()  

            except Exception as e:  

                print(f"   ❌ Delete failed: {e}")
```

--------------------------------

### Handle Non-SQL Questions

Source: https://docs.getwren.ai/cp/guide/api-access/quick-start

Demonstrates the request and error response when a question cannot be translated to SQL.

```bash
curl -X POST 'https://cloud.getwren.ai/api/v1/generate_sql' \

  -H 'Authorization: Bearer YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "projectId": YOUR_PROJECT_ID,

    "question": "What can you do?"

  }'
```

```json
{

  "id": "75c13d09-6f86-4e79-a00e-a4f85f73f2d7",

  "code": "NON_SQL_QUERY",

  "error": "User asks about Wren AI's features and capabilities, unrelated to database schema.",

  "explanationQueryId": "71b016c5-42bb-4897-82d6-46f9b0bf7d94"

}
```

--------------------------------

### Sync metadata

Source: https://docs.getwren.ai/cp/guide/cli/cli-reference

Synchronizes table and column descriptions from YAML files to the Wren AI project.

```bash
wren metadata sync --config /path/to/config-file.yaml
```

```bash
wren metadata sync --project-id <project-id>
```

```bash
wren metadata sync --config /path/to/config-file.yaml  --yes
```