Your First Stream

Let’s create your first event stream.

Prerequisites

Before starting, make sure you have:

1. Run xs nu --install once to install the Nushell integration
2. Started a new Nushell session (or run use xs.nu *)
3. Have two terminal windows ready: one for the server, one for the client

See the installation guide for details.

Serve

Unlike sqlite, which operates directly on the file system, xs requires a running process to manage access to the local store. This enables features like subscribing to real-time updates from the event stream.

Start an xs store in a dedicated window:

xs serve ./store

13:35:16.868 TRACE         event src/main.rs:185 Starting server with path: "./store"                                                                    xs:185
13:35:16.957  INFO         read options=ReadOptions { follow: On, tail: false, last_id: None, limit: None }                                      xs::store:174
13:35:16.957  INFO         read options=ReadOptions { follow: On, tail: true, last_id: None, limit: None }                                       xs::store:174
13:35:16.963  INFO     5ms insert_frame frame=Frame { id: "03d4por2p16i05i81fjy0fx8u", topic: "xs.start", hash: None, meta: None, ttl: None }    xs::store:410
13:35:16.963 0fx8u xs.start
13:35:16.968  INFO         read options=ReadOptions { follow: On, tail: false, last_id: None, limit: None }                                      xs::store:174

For a long-running setup you might run xs serve ~/.local/share/cross.stream/store under a process supervisor. This is the default location used by xs.nu when $env.XS_ADDR isn’t set. Here we keep the demo scoped to ./store.

To point tools at another store, set XS_ADDR. This can be done temporarily with with-env:

with-env {XS_ADDR: "./store"} { .cat }

Set XS_ADDR for this tutorial

Since we’re using ./store instead of the default location, set XS_ADDR in your client terminal before running any commands:

$env.XS_ADDR = "./store" | path expand

Without this, the client will try to connect to the default path (~/.local/share/cross.stream/store) and fail with a connection error (on Windows, this may appear as “dead network (os error 10050)”).

Client

append command

OK! Let’s append our first event:

nushell

null | .append notes --meta {text: "a quick note"}

───────┬─────────────────────────────
 topic │ notes
 id    │ 03d4q1qhbiv09ovtuhokw5yxv
 hash  │
 meta  │ {text: "a quick note"}
 ttl   │ forever
───────┴─────────────────────────────

bash

echo -n | xs append ./store notes --meta '{"text":"a quick note"}'

{"topic":"notes","id":"03d4qic9vqkve1krajjtlbavd","hash":null,"meta":{"text":"a quick note"},"ttl":"forever"}

cat command

and then cat the stream:

nushell

.cat

─#─┬──topic───┬────────────id─────────────┬─hash─┬──────────meta──────────┬───ttl───
 0 │ xs.start │ 03d4q1o70y6ek0ig8hwy9q00n │      │                        │
 1 │ notes    │ 03d4q1qhbiv09ovtuhokw5yxv │      │ {text: "a quick note"} │ forever
───┴──────────┴───────────────────────────┴──────┴────────────────────────┴─────────

These are the raw frames on the stream. Structured data lives inline in the meta field. We have the full expressiveness of Nushell available to us — for example, we can read the note text directly:

.cat | last | $in.meta.text

a quick note

bash

xs cat ./store

{"topic":"xs.start","id":"03d4qiab9g5vagrlrvxa2vjw0","hash":null,"meta":null,"ttl":null}
{"topic":"notes","id":"03d4qic9vqkve1krajjtlbavd","hash":null,"meta":{"text":"a quick note"},"ttl":"forever"}

These are the raw frames on the stream. Structured data lives inline in the meta field:

xs cat ./store | tail -n1 | jq -r .meta.text

a quick note

When to use CAS

For binary content or large blobs, xs provides Content-Addressable Storage (CAS). Pipe content directly to .append and it gets stored in CAS, referenced by a content hash. For structured data, prefer --meta. Read more about the architecture.

.last command

Let’s submit another note:

nushell

null | .append notes --meta {text: "submit TPS report"}
.cat

─#─┬──topic───┬────────────id─────────────┬─hash─┬──────────────meta──────────────┬───ttl───
 0 │ xs.start │ 03d4q1o70y6ek0ig8hwy9q00n │      │                                │
 1 │ notes    │ 03d4q1qhbiv09ovtuhokw5yxv │      │ {text: "a quick note"}         │ forever
 2 │ notes    │ 03d4qbrxizqgav09m7hicksb0 │      │ {text: "submit TPS report"}    │ forever
───┴──────────┴───────────────────────────┴──────┴────────────────────────────────┴─────────

We can get the most recent note on the stream using the .last command:

.last notes

───────┬─────────────────────────────────
 topic │ notes
 id    │ 03d4qbrxizqgav09m7hicksb0
 hash  │
 meta  │ {text: "submit TPS report"}
 ttl   │ forever
───────┴─────────────────────────────────

.last notes | $in.meta.text

submit TPS report

bash

echo -n | xs append ./store notes --meta '{"text":"submit TPS report"}'
xs cat ./store

{"topic":"xs.start","id":"03d4qiab9g5vagrlrvxa2vjw0","hash":null,"meta":null,"ttl":null}
{"topic":"notes","id":"03d4qic9vqkve1krajjtlbavd","hash":null,"meta":{"text":"a quick note"},"ttl":"forever"}
{"topic":"notes","id":"03d4qjwnhwudlfyg1ygemmt7b","hash":null,"meta":{"text":"submit TPS report"},"ttl":"forever"}

We can get the most recent note on the stream using the last command:

xs last ./store notes

{"topic":"notes","id":"03d4qjwnhwudlfyg1ygemmt7b","hash":null,"meta":{"text":"submit TPS report"},"ttl":"forever"}

xs last ./store notes | jq -r .meta.text

submit TPS report

riffing

Finally, let’s pull a list of all our notes.

nushell

We can filter by topic and then pull out the text of each note:

.cat | where topic == "notes" | each { $in.meta.text }

───┬───────────────────
0 │ a quick note
1 │ submit TPS report
───┴───────────────────

Fun!

bash

xs cat ./store | jq -r 'select(.topic == "notes") | .meta.text'

a quick note
submit TPS report

Fun! If you haven’t already, check out the Nushell tab. xs pairs well with Nushell’s structured data pipeline.