nick/amethyst
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Updates event store readme

Browse Source
This commit is contained in:
Vitor Pamplona
2026-01-14 15:29:13 -05:00
parent 54ab70beb7
commit adb2f48fb5
1 changed files with 16 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
quartz/src/androidMain/kotlin/com/vitorpamplona/quartz/nip01Core/store/README.md
+16 -46
View File
@@ -5,10 +5,10 @@ This module implements an **Event Store** with nostr-native queries.
The goal was not to make the fastest database, since there could be multiple optimizations made if
consistency can be sacrificed, but a database that will never crash and never go corrupt.
## Responsibilities
## Features
- **Storage & Retrieval**:
Stores Nostr events and enables retrieval using Nostr filters
Stores Nostr events and retrieves using Nostr filters
- **Replaceable Events**:
- Old versions are removed when newer versions arrive.
@@ -18,35 +18,42 @@ consistency can be sacrificed, but a database that will never crash and never go
- Ephemeral events never stored.
- **NIP-40 Expirations**
- Manages expiration timestamps and prunes expired events.
- Prunes expired events.
- Blocks expired events from being reinserted
- **NIP-09 Deletion Events**
- Deletes by event id
- Deletes by address until the `created_at`
- Blocks deleted events from being re-inserted.
- GiftWraps are deleted by p-tag
- **NIP-62 Right to Vanish**
- Supports deleting an entire user until the `created_at` for enhanced privacy
- GiftWraps are deleted by p-tag
- **NIP-45 Counts**:
- Counts records matching Nostr filters
- **NIP-50 Full Text Search**:
- Implements content indexing and full text search supporting rich queries over event content.
- Custom content/tag indexing
- Rich queries over event content and tags
- Indexes updated on replaceables, deletions, vanish and expirations.
- **NIP-91: AND operator for tags**:
- Allows queries matching two or more tags at the same time
- **Immutable Tables**
Triggers ensure event immutability.
- Tables cannot be updated, only inserted and deleted.
## Indexing Strategy
The store indexes events using five dedicated tables:
- `event_headers`: stores the canonical event fields.
- `event_tags`: indexes tag values for fast filtering on tag-based queries.
- `event_tags`: indexes tag values as a hash for fast filtering on tag-based queries.
- `event_fts`: for the content of full text search
- `event_expirations`: to control when expired events must be deleted.
- `event_vanish`: to control up to when vanished accounts must be blocked.
SQL triggers ensure the **immutability of stored events**, preventing accidental or intentional
modifications.
## Querying
This module supports optimized query planning, producing efficient SQL for multi-filter evaluation
@@ -63,43 +70,6 @@ store.query(
)
```
Becomes
```sql
SELECT id, pubkey, created_at, kind, tags, content, sig FROM event_headers
INNER JOIN (
SELECT event_headers.row_id AS row_id
FROM event_headers
ORDER BY created_at DESC,id ASC
LIMIT 10
UNION
SELECT event_headers.row_id AS row_id
FROM event_headers
INNER JOIN event_fts ON event_fts.event_header_row_id = event_headers.row_id
WHERE event_headers.kind IN (1, 1111)
AND event_headers.pubkey = hexkey
AND event_fts MATCH "keywords"
ORDER BY created_at DESC, id ASC
LIMIT 100
UNION
SELECT event_headers.row_id AS row_id
FROM event_headers
INNER JOIN event_fts ON event_fts.event_header_row_id = event_headers.row_id
WHERE event_headers.kind = 20
AND event_fts MATCH "cats"
ORDER BY created_at DESC,id ASC
LIMIT 30
) AS filtered ON event_headers.row_id = filtered.row_id
ORDER BY created_at DESC,id
```
The union operations support complex filter lists while avoiding redundant data fetching and
duplicated outstreams.
## How to Use
The `EventStore` class provides a high-level interface for interacting with the event database.