For AI agents: the complete documentation index is available at https://silt-db.dev/llms.txt, the full documentation bundle is available at https://silt-db.dev/llms-full.txt, and this page is available as Markdown at https://silt-db.dev/guide/introduction.md.

    What is Silt?

    Silt stores JSON documents in SQLite and lets you work with them using MongoDB-shaped queries, updates, and aggregation pipelines. It is a JavaScript library for applications that want document-style data access and a persistent local database file.

    SQLite does the filtering, expression evaluation, sorting, grouping, and joins. JavaScript compiles your query to SQL and decodes the documents you request. Silt does not load a collection into an in-memory query engine.

    Silt is currently an unpublished alpha. You can evaluate it from the repository today. It implements a documented subset of MongoDB behavior over JSON; it does not provide the MongoDB server protocol or every MongoDB operator. Read the compatibility contract before depending on a particular feature.

    What can you build with it?

    Use caseHow Silt helps
    Local application dataKeep notes, tasks, settings, and other JSON documents in a persistent SQLite file. Query just the documents a screen needs.
    A small Node serviceUse a local database with familiar document filters and SQL-backed aggregation reports. The recommended server driver is better-sqlite3 with WAL.
    Reports across related collectionsGroup orders, calculate totals, and join customer data with $lookup, without fetching the collections into JavaScript.
    An offline Expo applicationUse the same asynchronous collection API through expo-sqlite on web, iOS, and Android. Platform setup is covered in the Expo guide.
    ShareDB or Teamplay persistenceStore ShareDB snapshots and operations in SQLite while preserving its query conventions. Start with the ShareDB guide, then Teamplay.

    The core library is useful on its own. ShareDB and Teamplay are optional integrations.

    A document API over SQL

    A database contains named collections. A collection holds plain JSON objects, each with a unique _id. Filters use operators such as $gte and $in; aggregations describe a sequence of stages such as $match, $group, and $lookup.

    find() and aggregate() return lazy cursors. Consuming a cursor executes its SQL. Use asynchronous iteration to process returned documents one at a time, or .toArray() when you want the complete result in a JavaScript array.

    Persistent storage avoids an automatic JavaScript copy of the database. It does not make every operation use constant memory: SQLite needs working space, and an aggregation can construct a large result document. Calling .toArray() also retains the requested result in your application.

    JSON first

    Documents contain strings, finite numbers, booleans, null, arrays, and plain nested objects. Missing fields and explicit null values remain distinct. Silt generates a UUID string when you omit _id; supplying your own string IDs is usually the simplest choice.

    Storage uses JSON text, not BSON or SQLite JSONB. Extended types such as Date, ObjectId, and Decimal128 are outside the current scope. An application can store a timestamp string or number, but that does not enable MongoDB date operators. Numeric behavior also depends on the SQLite version; the compatibility contract records the known limits.

    Unsupported operators fail explicitly. There is no JavaScript query fallback.

    Start small, then go deeper

    1. Quick start: run a persistent database example from the repository.
    2. Queries and updates: find documents, work with arrays, and change data.
    3. Aggregations and joins: build reports with grouping and $lookup.
    4. Indexes and transactions: tune selective reads and coordinate writes.

    The database API reference describes connection options and the complete public method surface. The advanced guides cover platform and framework integration once the basic collection API is familiar.