RIDA uses standard library Python and ordinary HTTP Range requests. The reader does not use a cloud-provider SDK, upload your files or fetch the index from the network.
Inspect prints index metadata. Fields answers which keys a dataset stores. Get reads one value and exits with a clear error when the record or field does not exist.
rida inspect UsersData.rida
rida fields UsersData.rida
rida get UsersData.rida ali city
rida folders old.ridaLocal and remote readers expose the same lookup methods: get, get_many, get_record, folder resolution and verification.
import rida
with rida.RidaFile("UsersData.rida") as data:
print(data.get("ali", "city"))
print(data.get_many("ali", ["name", "city"]))
print(data.get_record("ali"))Upload UsersData.rida to an object store or CDN. Keep the index with your application, pass its local path with index=, and pass the data file’s URL to the reader.
rida remote-get \
https://data.example.com/UsersData.rida \
ali city --index UsersIndex.ridaThe server must return the requested range and matching Content-Range. If it sends the whole file, RIDA stops instead of silently downloading everything.
bytes=14231-14373Build with --url to install the index in the local cache. Use rida cache, --no-cache, --cache-dir or RIDA_CACHE_DIR to manage it.
RemoteRidaFile keeps one HTTP connection per reading thread. Against Bunny CDN, average lookup fell from 89.0 ms to 25.9 ms.
get_many and get_record combine nearby fields into one range when the skipped gap is cheaper than another ~660-byte response header.
get returns one complete value. get_many returns a dictionary containing selected fields from one record. get_record returns all fields present in that record.
with rida.RidaFile("ItemsData.rida") as data:
title = data.get("item-101", "title")
summary = data.get_many("item-101", ["title", "price"])
record = data.get_record("item-101")Several fields do not always mean one request. Nearby ranges merge when the bytes skipped between them cost less than another response header: the current threshold is 660 bytes. Farther ranges remain separate. A merged response can contain those gap bytes; the reader skips them locally.
| Reference dataset read | Requests | Approximate response bytes |
|---|---|---|
| 34 fields requested separately | 34 | 26,800 B |
| The same record with get_record | 1 | 5,000 B |
These measurements include the response overhead from the reference test. Headers still add bytes to a small value payload; the exact overhead depends on the server.
A field name absent from the dataset raises KeyError in get_many. A valid dataset field missing from this particular record is omitted from the returned dictionary.
A very large value remains a very large read. The saving comes from excluding other fields and records, not from cutting inside the selected value.
rida inspect ItemsData.rida
rida fields ItemsData.rida
rida fields ItemsData.rida --json
rida folders ItemsData.rida
rida get ItemsData.rida item-101 titleinspect prints index metadata as JSON. fields lists field names and accepts a data path or HTTP URL with a local index; --json prints the field-name array. folders lists names in a folder map. A CLI get for a missing record or field exits with status 1 and a short error.
with rida.RidaFile("ItemsData.rida") as data:
for prefix, name in data.folders().items():
print(prefix, name)
folder = data.resolve("catalog", "products")
for record_id in data.records_under(folder):
print(record_id, data.get(record_id, "title"))Upload the data file using your storage provider. RIDA reads URLs; it does not upload files or sell hosting. Keep the matching index with your app. Use a public or signed HTTPS file URL that permits byte-range requests.
Amazon S3, Cloudflare R2, Google Cloud Storage, Azure Blob Storage, Backblaze B2 and Bunny Pull Zones offer byte-range interfaces. This is compatibility through HTTP, not a separate RIDA integration or a claim that every provider configuration was tested.
The reader sends Range and a rida/<version> User-Agent. It does not add a provider’s storage access-key header. The endpoint must reply with HTTP 206 and a matching Content-Range.
with rida.RemoteRidaFile(
"https://data.example.com/ItemsData.rida",
index="ItemsIndex.rida",
timeout=10,
) as data:
print(data.get_many("item-101", ["title", "price"]))An explicit index= takes priority over the URL’s cached index. If neither is available, opening the remote reader fails; it never downloads an index for you. Building with --url installs the matching index in the builder’s cache, not automatically on another user’s device.
The default cache is ~/.cache/rida on macOS and Linux, unless changed through RIDA_CACHE_DIR, --cache-dir or cache_dir=. Keep data and index from the same build together. When replacing a dataset, distribute its new index and map too; versioned URLs help prevent stale pairs.
rida cache
rida cache --clear --url https://data.example.com/ItemsData.rida
rida remote-get https://data.example.com/ItemsData.rida item-101 title --index ItemsIndex.rida --timeout 10
rida remote-get https://data.example.com/ItemsData.rida item-101 title --index ItemsIndex.rida --no-cache --no-keepaliveThe default request timeout is 30 seconds. Reuse one reader for repeated lookups: its HTTP connection is kept open per reading thread. --no-keepalive or keepalive=False disables connection reuse. Close a reader after use, preferably with a Python with block.
A normal field read does not hash the whole dataset. verify is an explicit full-file check: it streams every data byte and compares the digest with the index, so it takes longer than a lookup.
rida verify ItemsData.rida
{
"size_ok": true,
"catalog_ok": true,
"data_ok": true,
"ok": true
}This excerpt shows the report’s checks; the full report also includes file size, record count, codec and encryption status. Failure exits with status 1. Use rida.verify(path) or an open local reader’s verify_data() in Python. Pass the key for an encrypted dataset.