SampleSift provides spatial search for geolocated records. Django collections store typed fields in derived PostgreSQL tables. The Lit frontend displays filters, result tables, and clustered MapLibre tiles. An optional Jupyter widget embeds the frontend in notebooks.
Use Python 3.12 or newer. Install the integration for your application:
pip install 'samplesift[django]'
# Or install the notebook wrapper:
pip install 'samplesift[jupyter]'
pip install samplesift installs the base package without optional integrations.
Spatial Django collections require PostGIS.
The Jupyter wrapper currently requires a running frontend server and collection API.
The repository includes a Django backend with 9,900 OBIS occurrence records. The frontend uses that backend for filters, results, and map clusters.
Install Node.js 22.12 or newer, npm, Task, and Docker Compose 2.24.4 or newer. From the repository root:
task frontend:setup
task dev
Open the Vite URL from the terminal. API documentation is at http://127.0.0.1:8002/samplesift/docs. Ctrl-C stops the development servers. The database volume remains available.
See development tasks for individual servers, ports, and checks. See the OBIS example for dataset details and standalone Docker setup.
Declare collections in an installed app's samplesift.py:
from samplesift.django import Point, SampleSiftCollection, registry
from .models import Sample
@registry.register
class SampleCollection(SampleSiftCollection):
fields = ["lat", "lon", "temperature", "species_name"]
geometry = Point(longitude="lon", latitude="lat")
class Meta:
model = Sample
api_name = "samples"
class Query:
default_ordering = ["-temperature"]
This example assumes those fields exist on your Sample model.
Django ORM saves and deletes synchronise collection rows after the source transaction commits.
Bulk updates, raw SQL, and related-object changes do not synchronise automatically.
Follow Django collections for app registration, database configuration, schema setup, and API routes.
Use typed properties and resolvers for computed or related fields.
Use JSON metadata properties for values inside a JSONB field.
The spatial query API documents CQL2 filters, pagination, and vector tiles over HTTP QUERY.
From a source checkout, install the notebook environment:
task jupyter:setup
Keep task dev running in one terminal.
Open the example notebook in another terminal:
task jupyter:lab
The example notebook demonstrates filters, polygon searches, linked sliders, and DataFrame exports. See Jupyter setup and limits for widget configuration and Python bindings.
| Topic | Guide |
|---|---|
| Django declarations, resolvers, API, and settings | Django collections |
| Cache configuration, invalidation, and prewarming | Tile caching |
| Frontend setup and embedding | Frontend guide |
| Frontend state, events, and collection API | Component API |
| Frontend and backend development tasks | Development tasks |
| Themes and styling | Frontend styling |
| Notebook setup and Python bindings | Jupyter wrapper |
| Python dependencies, Git hooks, and lint | Development checks |
| Component package validation and publishing | Frontend release guide |
| Longer-term design | Spatial collection architecture |
Install Python development dependencies and the Git hook:
uv sync --locked
task hooks:install
Use task jupyter:setup instead of uv sync for notebook development.
Run task lint for the pinned pre-commit checks.
Run task frontend:check for frontend lint, types, and unit tests.
See development checks for hook setup details.
See Django verification for PostGIS tests.
The Python package lives in src/samplesift/.
The npm workspace lives in frontend/.
Python and frontend packages have independent release cycles.