Skip to content

Connecting to Servers

arrakis connects to an Arrakis server using the Apache Arrow Flight protocol over gRPC. There are several ways to configure the server address.

Default Server

If no URL is specified, arrakis connects to the address in the ARRAKIS_SERVER environment variable. If that is not set, it falls back to grpc://0.0.0.0:31206.

Setting the Server URL

Environment variable

export ARRAKIS_SERVER="grpc://my-server:31206"

Python API

Pass the URL when creating a arrakis.client.Client:

import arrakis

client = arrakis.Client(url="grpc://my-server:31206")

The top-level convenience functions (fetch, stream, find, etc.) do not accept a URL directly -- use the Client class when you need to specify one.

CLI

Use the --url flag:

arrakis --url grpc://my-server:31206 find "H1:.*"

SSH Tunneling

If the Arrakis server is not directly reachable, the CLI can create an SSH tunnel:

arrakis --ssh-proxy login.example.com find "H1:.*"

This:

  1. Connects to login.example.com via SSH.
  2. Reads the ARRAKIS_SERVER variable from the remote environment (unless --url is also specified).
  3. Opens a local port forwarding tunnel to the remote server.
  4. Runs the arrakis command through the tunnel.

You can combine --ssh-proxy with --url to explicitly set the remote server address:

arrakis --ssh-proxy login.example.com --url grpc://internal-server:31206 find "H1:.*"

Server Information

Use arrakis.api.server_info to retrieve metadata about the server you are connected to, including version info, backend type, and capabilities:

import arrakis

info = arrakis.server_info()
print(info)

Use arrakis.api.domains to list the domains (detector sites) available on the server:

domains = arrakis.domains()
print(domains)  # e.g. ["H1", "L1"]

Kafka URLs

For streaming, the server may direct the client to a Kafka endpoint instead of a Flight endpoint. This is handled transparently. You can also specify a Kafka URL explicitly via the CLI:

arrakis stream H1:CAL-DELTAL_EXTERNAL_DQ --kafka-url kafka://broker:9092

In the Python API, pass kafka_url to arrakis.client.Client.stream:

client = arrakis.Client()
for block in client.stream(channels, kafka_url="kafka://broker:9092"):
    print(block)