# Geosql

Build cost-safe geospatial SQL for BigQuery, DuckDB, Snowflake, Wherobots, and Postgres...

- Repository: https://github.com/dekart-xyz/geosql (682 stars)
- Category: Data and ML
- License: MIT
- Last updated: 2026-10-09
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dekart-xyz/geosql --skill geosql -g -a claude-code -y`
Codex: `npx skills add dekart-xyz/geosql --skill geosql -g -a codex -y`
Cursor: `npx skills add dekart-xyz/geosql --skill geosql -g -a cursor -y`
Gemini CLI: `npx skills add dekart-xyz/geosql --skill geosql -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add dekart-xyz/geosql`

## Description

Build cost-safe geospatial SQL for BigQuery, DuckDB, Snowflake, Wherobots, and Postgres and/or render results on an interactive Dekart map.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# GeoSQL

## Tools/CLI

This skill uses the following CLIs:
- `dekart` for running BigQuery, DuckDB, Snowflake, Wherobots, and Postgres SQL and rendering maps
- `bq` to run BigQuery SQL when `dekart` BigQuery integration is not available.
- `snow` to run Snowflake SQL when `dekart` Snowflake integration is not available.
- Wherobots and Postgres have no local CLI fallback; they are dekart-only in this skill.

Before using CLIs, verify availability if it was not done before:

```bash
for c in bq snow dekart; do command -v $c >/dev/null && echo $c=ok || echo $c=missing; done
```

If no CLI is available, suggest installing the dekart CLI: `pip install dekart && dekart init`. `dekart init` is an interactive command that must be run by the user.

The user has 3 options in `dekart init`:
- cloud.dekart.xyz (Dekart-hosted control plane, easier setup)
- localhost (`docker run -p 8080:8080 dekartxyz/dekart`, more secure, requires Docker)
- self-hosted

Help the user pick the best installation option for their needs.

If `dekart` is available, check available connectors:

```bash
dekart call --name list_connections --args '{}' --json
```

If dekart available but not init, ask user to `dekart init`


## Dialect References

Use the matching reference for per-database SQL, CLI examples, and engine-specific caveats:

- BigQuery: `references/bigquery.md`
- DuckDB: `references/duckdb.md`
- Snowflake: `references/snowflake.md`
- Postgres / PostGIS: `references/postgres.md`
- Wherobots / Sedona: `references/wherobots.md`

Dekart map references:

- Map config (`update_report_map_config`): `references/map-config.md`
- Charts (widgets): `references/widgets.md`
- Styling: `references/map-styling.md`

## Required Workflow

Follow these steps in order. Do NOT write a final query until steps 1-3 are complete.
Combine each step with examples in matching dialect reference.

### Step 1: Discover schema

The rest: https://github.com/dekart-xyz/geosql/blob/HEAD/skills/geosql/SKILL.md