Database Operations

SpatialDatabase

The entry point for all database operations. Wraps a SQLite database with spatial capabilities.

Creating a database

// File-backed database
using var db = new SpatialDatabase("mydata.db");

// In-memory database (useful for testing)
using var db = new SpatialDatabase(":memory:");

Tip

Always use using to ensure the database connection is properly closed and disposed.

Table management

// Create a new spatial table
var table = db.CreateTable(
    "cities",
    CoordinateSystem.Wgs84,
    new PropertyDefinition("name", PropertyType.Text),
    new PropertyDefinition("population", PropertyType.Integer),
    new PropertyDefinition("area", PropertyType.Real)
);

// Get an existing table
var table = db.GetTable("cities");

// Check if a table exists
bool exists = db.TableExists("cities");

// Drop a table
db.DropTable("cities");

Coordinate systems

System	Description	Distance Calculation
CoordinateSystem.Wgs84	GPS/geographic coordinates (longitude/latitude)	Haversine (great-circle)
CoordinateSystem.Cartesian	Flat Euclidean coordinate system	Euclidean distance

Note

The coordinate system affects how distance calculations are performed in spatial queries. WGS84 uses the Haversine formula for accurate great-circle distances on Earth. Cartesian uses simple Euclidean distance.

Property types

Type	Description	.NET Type
PropertyType.Text	String values	string
PropertyType.Integer	Whole numbers	long
PropertyType.Real	Floating-point numbers	double
PropertyType.Blob	Binary data	byte[]

SpatialTable

Represents a spatial table and provides all CRUD and query operations.

Properties

Property	Type	Description
Name	string	Table name
CoordinateSystem	CoordinateSystem	WGS84 or Cartesian
Properties	IReadOnlyList<PropertyDefinition>	User-defined property definitions

SpatialFeature

A container that holds a geometry and its associated properties.

// Create a feature with properties
var feature = new SpatialFeature(new Point(-104.99, 39.74))
{
    Properties =
    {
        ["name"] = "Denver",
        ["population"] = 715000L
    }
};

Property	Type	Description
Id	long	Feature ID (assigned after insert)
Geometry	Geometry	The spatial geometry
Properties	Dictionary<string, object?>	User-defined properties

Insert Operations

Single insert

var feature = new SpatialFeature(new Point(-104.99, 39.74))
{
    Properties = { ["name"] = "Denver", ["population"] = 715000L }
};

long id = table.Insert(feature);

Bulk insert

Wraps all inserts in a single transaction for better performance (~20% faster than individual inserts).

var features = new List<SpatialFeature>
{
    new SpatialFeature(new Point(-104.99, 39.74))
    {
        Properties = { ["name"] = "Denver", ["population"] = 715000L }
    },
    new SpatialFeature(new Point(-105.27, 40.01))
    {
        Properties = { ["name"] = "Boulder", ["population"] = 105000L }
    }
};

table.BulkInsert(features);

Tip

Use BulkInsert when inserting more than a handful of features. At 100K features, bulk insert completes in ~964ms vs ~1204ms for individual inserts.

Read Operations

Get by ID

var feature = table.GetById(1);
if (feature != null)
{
    var name = feature.Properties["name"];
    var geometry = feature.Geometry;
}

Count

long total = table.Count();

Update Operations

var feature = table.GetById(1)!;
feature.Properties["population"] = 750000L;
table.Update(feature);

Delete Operations

bool deleted = table.Delete(1); // returns true if feature existed