Table of Contents

Spatial

foundry spatial works with Geometry/Geography column data from a table. It has two subcommands: view plots Point values on a terminal canvas for a quick visual check, and export writes the full geometry plus other column values to a GeoJSON file for use in a GIS tool or web map.

foundry spatial view [options]
foundry spatial export [options]

View

foundry spatial view plots Point values from a Geometry or Geography column directly in the terminal, using a character-cell canvas. It's useful for a quick "where are my points" sanity check on spatial data without opening a GIS tool.

foundry spatial view [options]

Options

Option Short Description
--datasource <FILE> -d Datasource JSON file
--conn <STRING> -c ADO.NET connection string
--db <TYPE> -b Database engine type
--schema <NAME> -s Name of the schema containing the table (required)
--table <NAME> -t Name of the table containing the spatial column (required)
--geo-column <COLUMN> -g Name of the Geometry or Geography column to plot (required)
--limit <N> -l Maximum number of rows to fetch and plot (default: 2000)
--width <N> -W Canvas width in characters (default: current terminal width, or 80 if not running in a terminal)
--height <N> -H Canvas height in characters (default: current terminal height minus three lines for the status/summary output, or 40 if not running in a terminal)
--log-config <FILE> -L Log configuration file
--verbose -v Print SQL as it executes

Examples

# Plot a Geometry column
foundry spatial view --datasource connection.json --schema public --table locations --geo-column geom

# Plot a Geography column with a larger canvas
foundry spatial view \
  --datasource SqlServer_16.0.json \
  --schema dbo --table sites --geo-column geog \
  --limit 5000 --width 100 --height 50

# Inline connection string
foundry spatial view \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --schema dbo --table sites --geo-column geog

Sample output:

                                                            ▀
                                                         ▄▀▄ ▀ ▀       ▀
                                                                 ▄             ▄
                             ▄ ▄ ▄ ▄ ▄ ▄▄▄▄▄ ▄              ▀              ▀▄  ▀
                          ▄▀ ▀ ▄  ▄ ▀▀▀ ▀ ▄ ▄▀ ▀▄ ▄                          ▄
                    ▄ ▀ ▀  ▄ ▀                ▀ ▄   ▀ ▄      ▄ ▄   ▄  ▀
X: -124.0321 to -121.1789   Y: 36.2002 to 38.2875   |   151 points plotted, 30 null or non-point values skipped

How Points Are Plotted

For each row, Foundry reads the value of --geo-column and extracts its coordinate. The full result set's bounding box (min/max X and Y) is computed first, then every point is normalized into that range and mapped onto the canvas — so the plot always fills the requested --width/--height regardless of the data's real-world scale. The Y axis is flipped so that higher latitude/Y values render toward the top, matching how a map normally looks.

The axis range printed beneath the canvas (X: ... to ... Y: ... to ...) is the bounding box of the plotted points only, not the column's full domain — useful for sanity-checking how spread out your data actually is.

If a table has fewer than two distinct X or Y values (e.g. every point shares the same longitude), Foundry pads the range slightly so the plot doesn't divide by zero — you'll see a single column or row of points rather than a crash.

Polygons and Lines Are Not Plotted

foundry spatial view only plots Point geometries. Any row whose geometry is a Polygon, LineString, MultiPoint, MultiPolygon, or other non-Point type is skipped entirely — it is not approximated by its centroid or first vertex, just left out of the plot. Skipped rows (along with NULL values in the column) are counted and reported together at the end, alongside the axis range, on a single line below the canvas:

X: -124.0321 to -121.1789   Y: 36.2002 to 38.2875   |   151 points plotted, 30 null or non-point values skipped

If every row in the result set is non-Point (or NULL), no canvas is drawn at all — Foundry prints No point geometries found to plot. and exits cleanly with status 0, rather than rendering an empty canvas.

Note

Rendering LineString/Polygon geometries as actual shapes — rather than skipping them — would require rasterizing line and polygon edges onto the canvas (Foundry's canvas only supports setting individual points), which foundry spatial view does not currently do. If your column is mixed-geometry and you specifically want polygon/line boundaries preserved, use foundry spatial export to write the full geometry to a GeoJSON file instead.

Choosing --limit

The canvas has a fixed resolution (--width × --height character cells), so plotting more points than there are cells mostly just slows down the query without improving the picture — multiple points landing in the same cell simply overwrite each other. The default --limit of 2000 is a reasonable balance for most tables; raise it for a denser sample, or lower it for a faster preview on a very large table.

Canvas Sizing

When --width/--height are omitted, Foundry sizes the canvas to fill the current terminal — the whole plot fits on screen without scrolling. Height is set three lines short of the terminal's full height, leaving room for the status line printed while fetching, the axis-range/summary line printed below the canvas, and the shell prompt line that follows. When output isn't a terminal (piped to a file, redirected in a script, or run in CI), Foundry falls back to a fixed 80×40 canvas instead, since there's no real terminal size to read. Pass --width/--height explicitly to override either default.

Export

foundry spatial export exports the geometry/geography data and other column values from a table to a GeoJSON file, ready to load into a GIS tool, web map, or another system that consumes GeoJSON.

foundry spatial export [options]

Options

Option Short Description
--datasource <FILE> -d Datasource JSON file
--conn <STRING> -c ADO.NET connection string
--db <TYPE> -b Database engine type
--schema <NAME> -s Name of the schema containing the table (required)
--table <NAME> -t Name of the table containing the spatial column (required)
--geo-column <COLUMN> -g Name of the Geometry or Geography column to export (required)
--id-column <COLUMN> -i Name of the column promoted to each GeoJSON Feature's top-level id (default: a column literally named id, if present)
--property-columns <COLUMNS> -p Comma-separated list of columns to include as GeoJSON feature properties (default: all columns)
--format <FORMAT> -F Output format (default: GeoJson, currently the only supported value)
--out <FILE> -o Output file path (required)
--log-config <FILE> -L Log configuration file
--verbose -v Print SQL as it executes

Examples

# Export every column as GeoJSON properties
foundry spatial export \
  --datasource connection.json \
  --schema public --table locations --geo-column geom \
  --out locations.geojson

# Promote a column to the Feature's top-level "id"
foundry spatial export \
  --datasource SqlServer_16.0.json \
  --schema dbo --table sites --geo-column geog \
  --id-column SiteID --out sites.geojson

# Limit which columns become properties
foundry spatial export \
  --datasource SqlServer_16.0.json \
  --schema dbo --table sites --geo-column geog \
  --property-columns "Name,Category" --out sites.geojson

# Inline connection string
foundry spatial export \
  --conn "Server=localhost;Database=mydb;User Id=sa;Password=pass" \
  --db SQLServer \
  --schema dbo --table sites --geo-column geog \
  --out sites.geojson

How Export Works

Foundry queries the table for the geometry/geography column plus whichever other columns are selected, then streams the result set to the output file as a GeoJSON FeatureCollection — one row at a time, so memory use stays flat regardless of table size. Each row becomes one GeoJSON Feature: the value of --geo-column becomes the Feature's geometry, and every other selected column becomes an entry in the Feature's properties object.

Unlike foundry spatial view, which only handles Point values, spatial export supports any geometry type — Point, LineString, Polygon, and their Multi* counterparts all export correctly, since GeoJSON itself can represent all of them.

Choosing Properties

By default, every column in the table is included as a GeoJSON property. Use --property-columns to export only specific columns — useful for large tables where most columns aren't relevant to the map/GIS use case:

foundry spatial export --datasource connection.json --schema public --table locations --geo-column geom \
  --property-columns "name,category,last_updated"

--geo-column is always included in the query regardless of --property-columns (it becomes the Feature's geometry, not a property). If --id-column is specified, it's likewise always included even if omitted from --property-columns.

Feature IDs

GeoJSON Features can carry an optional top-level id alongside their properties. By default, Foundry looks for a column literally named id (exact case) among the selected properties and promotes it automatically. Use --id-column to promote a different column instead — matched against the exact column name as it appears in the table:

foundry spatial export --datasource connection.json --schema dbo --table sites --geo-column geog \
  --id-column SiteID --out sites.geojson

The promoted column is removed from properties once promoted — it appears only as the Feature's top-level id, not duplicated in both places.