Downloads 586this week

GitHub stars 22

Extension descriptor (YAML)

Query NATS JetStream message streams directly with SQL

Compatibility Matrix

This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

Installing and Loading

INSTALL nats_js FROM community;
LOAD nats_js;

Example

-- Read messages from a stream (the server defaults to nats://localhost:4222)
SELECT subject, seq, ts_nats, payload
FROM nats_scan('telemetry', start_seq := 1, end_seq := 100);

-- Filter subjects with NATS wildcards and extract JSON fields, including nested ones
SELECT seq, device_id, location_zone, kw
FROM nats_scan('telemetry',
    subject := 'telemetry.*.power.>',
    json_extract := ['device_id', 'location.zone', 'kw']
);

-- Extract Protocol Buffers fields with native types
SELECT device_id, location_zone, metrics_kw
FROM nats_scan('telemetry_proto',
    proto_file := 'telemetry.proto',
    proto_message := 'Telemetry',
    proto_extract := ['device_id', 'location.zone', 'metrics.kw']
);

About nats_js

The nats_js extension reads the messages stored in NATS JetStream streams with SQL. It creates no consumers.

Features:

• Subject filters with NATS wildcards, applied by the server
• Sequence ranges (start_seq, end_seq) and time ranges (start_time, end_time)
• JSON field extraction with dot paths for nested fields
• Protocol Buffers decoding from a .proto file at query time, with native DuckDB types
• Streams with or without allow_direct

Documentation: https://github.com/brannn/duckdb-nats-jetstream

Added Functions

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings

This extension does not add any settings.