Language bindings
The Terra Core Library is written in C. Six bindings and a command-line tool wrap it, each following the naming conventions of its own language rather than imposing C's.
| Binding | Package | Naming | Cell type |
|---|---|---|---|
| Python | terra-sa | snake_case | str (TIS) |
| JavaScript | terra-sa | camelCase | string |
| PostgreSQL | terra extension | terra_snake_case | bigint / text |
| Go | github.com/tec-solution-ksa/terra-go | PascalCase | terra.Index |
| R | terrasar | snake_case | character |
| DuckDB | terra extension | terra_snake_case | UBIGINT / VARCHAR |
| CLI | terra | subcommands | text |
Installation for each is covered in Installation.
Choosing a binding
Python — analysis, ingest pipelines, and data science. The most complete binding and the one to reach for when exploring.
JavaScript — browser and Node. Compiled to WebAssembly from terra-core, so it derives geometry
client-side without a server round trip.
PostgreSQL — where the data already lives. Indexing a column and joining on cells is usually faster than moving rows out to index them elsewhere.
Go — services. A pure Go implementation with no CGo dependency, so it cross-compiles and containerises cleanly.
R — statistical work and reporting, vectorised over columns.
DuckDB — analytical queries over files. Useful for indexing Parquet or CSV without loading into a database first.
CLI — inspection, debugging, and shell pipelines. The quickest way to check what a cell is.
Cell representation
Bindings differ in how they carry a cell, and the difference matters.
String bindings (Python, JavaScript, R) use the 17-character TIS. Safe everywhere, immune to precision loss, slightly larger in memory.
Integer bindings (Go, PostgreSQL, DuckDB) use the native 64-bit value. Faster and more compact.
JavaScript never uses a Number for a cell. Every Terra index exceeds
Number.MAX_SAFE_INTEGER, so a cell held in a Number is silently corrupted. The binding uses
strings; use BigInt if you need arithmetic.
When passing cells between systems, the TIS is the interchange form. It survives JSON, CSV, and any language boundary without ambiguity about width or signedness.
Consistency across bindings
All bindings wrap the same C core, so results are identical. A cell computed in Python and one computed in PostgreSQL from the same coordinate and resolution are the same cell, bit for bit.
Two exceptions to be aware of:
Error reporting differs by language. Exceptions in Python, thrown errors in JavaScript, returned
errors in Go, SQL exceptions or NULL in PostgreSQL. See
Error handling.
Vectorisation differs. R and the database bindings operate over columns; Python and JavaScript operate on single values unless you use the batch entry points. For large workloads, prefer the batch forms — per-call overhead across a binding boundary dominates at scale.
Writing a new binding
The core library is designed to be wrapped. If you need a language not listed here, see Creating bindings for the C interface and the conformance tests any binding must pass.
Next
- Installation — installing each binding
- Applications — how the grid is used in practice
The Terra System is designed and developed by Tec Solution KSA.