Getting Started with CQLAI¶

CQLAI is a modern, AI-powered CQL shell for Apache Cassandra that enhances productivity with intelligent query suggestions, data analysis, and seamless import/export capabilities.

What is CQLAI?¶

CQLAI is a next-generation command-line interface for Cassandra that combines: - Modern CQL Shell - Fast, feature-rich alternative to cqlsh - AI Assistance - Natural language to CQL translation - Data Tools - Easy import/export with multiple formats - Enhanced UX - Syntax highlighting, auto-completion, query history

Installation¶

Download Binary¶

# Linux (AMD64)
curl -L https://github.com/axonops/cqlai/releases/latest/download/cqlai-linux-amd64 -o cqlai
chmod +x cqlai
sudo mv cqlai /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/axonops/cqlai/releases/latest/download/cqlai-linux-arm64 -o cqlai
chmod +x cqlai
sudo mv cqlai /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/axonops/cqlai/releases/latest/download/cqlai-darwin-amd64 -o cqlai
chmod +x cqlai
sudo mv cqlai /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/axonops/cqlai/releases/latest/download/cqlai-darwin-arm64 -o cqlai
chmod +x cqlai
sudo mv cqlai /usr/local/bin/

Using Homebrew (macOS)¶

brew install axonops/tap/cqlai

Verify Installation¶

cqlai --version

Quick Start¶

Connect to Cassandra¶

# Local connection (default: localhost:9042)
cqlai

# Specify host and port
cqlai -h 192.168.1.10 -p 9042

# With authentication
cqlai -h 192.168.1.10 -u cassandra -p cassandra

# Connect to specific keyspace
cqlai -h 192.168.1.10 -k my_keyspace

Basic Commands¶

-- List keyspaces
DESCRIBE KEYSPACES;

-- Use a keyspace
USE my_keyspace;

-- List tables
DESCRIBE TABLES;

-- Run a query
SELECT * FROM users LIMIT 10;

-- Exit
EXIT;

AI Features¶

Natural Language Queries¶

# Enable AI mode with provider
cqlai --ai-provider openai --ai-key YOUR_API_KEY

# Or set environment variable
export CQLAI_AI_PROVIDER=openai
export CQLAI_AI_KEY=YOUR_API_KEY
cqlai

Ask AI¶

cqlai> .ai show me all users who signed up last month

Generated CQL:
SELECT * FROM users
WHERE created_at >= '2024-11-01' AND created_at < '2024-12-01'
ALLOW FILTERING;

Execute? [Y/n]:

Schema Suggestions¶

cqlai> .ai suggest a schema for storing IoT sensor data

Suggested schema:
CREATE TABLE sensor_readings (
    sensor_id text,
    bucket text,
    reading_time timestamp,
    temperature double,
    humidity double,
    PRIMARY KEY ((sensor_id, bucket), reading_time)
) WITH CLUSTERING ORDER BY (reading_time DESC);

Explanation:
- Partition by sensor_id and time bucket for even distribution
- Cluster by time for efficient range queries
- Descending order for latest-first queries

Data Import/Export¶

Export Data¶

# Export to CSV
cqlai> .export users /tmp/users.csv

# Export to JSON
cqlai> .export users /tmp/users.json --format json

# Export query results
cqlai> .export "SELECT * FROM orders WHERE status = 'pending'" /tmp/pending.csv

Import Data¶

# Import from CSV
cqlai> .import /tmp/users.csv users

# Import from JSON
cqlai> .import /tmp/users.json users --format json

# Preview before import
cqlai> .import /tmp/users.csv users --preview

Configuration¶

Configuration File¶

CQLAI supports both JSON and YAML configuration formats:

// ~/.config/cqlai/config.json (or ~/.cqlai.json or ./cqlai.json)
{
  "host": "localhost",
  "port": 9042,
  "username": "cassandra",
  "keyspace": "default_ks",
  "pageSize": 100,
  "ai": {
    "provider": "openai",
    "model": "gpt-4"
  }
}

See Configuration for all available options and file locations.

Environment Variables¶

# Connection
export CQLAI_HOST=192.168.1.10
export CQLAI_PORT=9042
export CQLAI_USERNAME=cassandra
export CQLAI_PASSWORD=secret

# AI
export CQLAI_AI_PROVIDER=openai
export CQLAI_AI_KEY=sk-...
export CQLAI_AI_MODEL=gpt-4

Keyboard Shortcuts¶

Shortcut	Action
`Tab`	Auto-complete
`Ctrl+R`	Search history
`Ctrl+C`	Cancel query
`Ctrl+D`	Exit
`Up/Down`	Navigate history

Command Reference¶

Command	Description
`.help`	Show help
`.ai <prompt>`	AI natural language query
`.export <table> <file>`	Export data
`.import <file> <table>`	Import data
`.desc <table>`	Describe table
`.clear`	Clear screen
`.history`	Show command history
`.settings`	Show current settings

Next Steps¶

Features - Full feature reference
AI Features - AI capabilities
Data Import/Export - Data migration
Configuration - Advanced configuration