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, an SSH tunnel can be created automatically by specifying an ssh:// server URL:

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

This:

  1. Connects to login.example.com via SSH.
  2. Reads the ARRAKIS_SERVER variable from the remote environment to determine the server address (unless one is given in the URL, see below).
  3. Opens local port forwarding tunnels to the server and all of its data endpoints.
  4. Starts a transient local proxy server that transparently redirects requests through the tunnels, and runs the arrakis command against it.

The remote server address may also be given explicitly as part of the URL, in the form ssh://host[:port][::rhost[:rport]]:

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

Note

Publishing is not supported through the SSH proxy; only read operations (find, describe, count, fetch, stream) are available.

Persistent proxies

Each CLI invocation with an ssh:// URL sets up and tears down its own tunnel. To hold a proxy open across multiple commands, use the exec subcommand, which runs the wrapped command with ARRAKIS_SERVER pointing at the proxy (or, with no command, blocks and prints the proxy address until interrupted):

arrakis --url ssh://login.example.com exec -- python my_script.py

By default the proxy binds to localhost:31206; use arrakis exec --bind HOST:PORT to bind elsewhere.

Python API

The same functionality is available in Python via arrakis.proxy.ssh_proxy, which yields the local proxy URL:

import arrakis
from arrakis.proxy import ssh_proxy

with ssh_proxy("ssh://login.example.com") as url:
    client = arrakis.Client(url)
    print(client.count("H1:.*"))

The proxy is shut down when the context exits, so all requests must be made within the with block.

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)