Live — API Reference

Live([key]; dataset, gateway=nothing, port=13000, ts_out=false,
     heartbeat_interval=nothing, channel_size=10_000, typed=false)

Client for the Databento Live (TCP) API.

Lifecycle: connect! → subscribe! (one or more times) → start! → iterate (for rec in client) or subscribe_callback → close(client).

A single Live is bound to ONE dataset. Multi-dataset workflows need multiple clients.

Typed mode (typed = true)

Under typed mode, each subscribed schema gets its own Channel{T} for the concrete record type — no per-record Union boxing, type-stable consumer code. subscribe! returns the typed channel directly; the user owns it and reads via for rec in ch; ...; end. Control records (ErrorMsg, SystemMsg, SymbolMappingMsg) route to a dedicated channel exposed as control_channel(client). Iterating for rec in client errors under typed mode — point users at the per-channel pattern instead.

Typed mode requires every subscribed schema to map to a concrete record type (i.e. DBN.record_type_for_dbn_schema(schema) returns non-nothing). Subscribing to a mixed-record schema like Schema.MIX errors at subscribe!.

Default typed = false preserves the original single-Channel{DBN.DBNRecord} behaviour exactly — no migration needed for existing code.

connect!(client)

Open the TCP connection, perform the CRAM authentication handshake. After this returns, the client is ready for subscribe! calls. Throws BentoAuthError on failure.

subscribe!(client; schema, symbols, stype_in=SType.RAW_SYMBOL,
           snapshot=false, start=nothing) -> Int | Channel{T}

Send a subscription request to the Live gateway. May be called multiple times before start!.

Return type depends on the client's mode:

• Untyped (Live(...; typed=false), the default): returns an Int sub_id. All records flow into the single client.channel :: Channel{DBN.DBNRecord}.
• Typed (Live(...; typed=true)): returns the Channel{T} for the concrete record type bound to this schema. Multiple subscribes to the same schema (different symbols) share one channel — records of the same type land together. Subscribing under typed mode to a schema with no concrete record type (e.g. Schema.MIX) errors.

snapshot=true (request an order book snapshot) is mutually exclusive with start.

subscribe_callback(client, fn) -> Task

Spawn a task that pulls every record from client and passes it to fn(record). Returns the task. Use this for low-overhead event-driven loops; otherwise iterate.

Untyped mode only. For typed mode, register one task per subscribed channel directly:

ch = subscribe!(client; schema = Schema.TRADES, symbols = ...)
@async for rec in ch; fn(rec); end

start!(client)

Tell the gateway to begin streaming. After this returns, records flow into the client's channel(s) and can be consumed via iteration or subscribe_callback.

stop!(client)

Tell the gateway to stop streaming. Does not close the socket. Records already in the channel can still be consumed.

channel(client::Live, schema::Schema.T) -> Channel{T}

Return the typed data channel for the given subscribed schema. Errors if the client is untyped or if the schema has not been subscribed.

control_channel(client::Live) -> Channel{DBN.DBNRecord}

Return the channel carrying control records (ErrorMsg, SystemMsg, SymbolMappingMsg) for a typed-mode Live. Errors if the client was constructed with typed = false (in that mode, control records arrive on the main client.channel alongside data records).