Client configuration

QueryClient(
    workspace_name=None,
    project_name=None,
    api_key=None,
    query_url=None,
    request_timeout=30.0,
    connect_timeout=10.0,
    ca_bundle=None,
)

Identity

Argument	Environment fallback	Notes
workspace_name	METRANA_WORKSPACE	Required. Fixed for the client’s lifetime.
project_name	METRANA_PROJECT	Only a default; every method takes project_name=.
api_key	METRANA_API_KEY	Optional; omitting it connects anonymously.
query_url	METRANA_QUERY_API_URL	Falls back to query_api_url from metrana.init() before the environment variable; defaults to https://query.metrana.ai. See Service endpoints.

The project is genuinely optional — a client used only for workspace-wide listings never needs one. Methods that do need one raise ConfigError when neither the call nor the client supplies it.

Both can be changed after construction:

client.workspace_name          # read-only property
client.default_project
client.set_default_project("other-project")
client.set_api_key(rotated)    # for a long-lived session

Without any key the client connects anonymously, which can read public workspaces only.

Timeouts

Argument	Default	Meaning
connect_timeout	10 s	Connection establishment, at construction.
request_timeout	30 s	Per-request deadline, propagated to the server. None disables it.

Construction connects eagerly and raises TransportError if the endpoint is unreachable, rather than deferring the failure to your first query.

request_timeout is per request, not per method call — a fetch_ that depaginates over many pages gives each page the full deadline. For a genuinely large export, None removes the deadline rather than needing a guessed large number.

TLS

For an https:// endpoint the client trusts, in order of preference:

1. ca_bundle= — an explicit PEM file of trusted roots.
2. SSL_CERT_FILE, then REQUESTS_CA_BUNDLE, then GRPC_DEFAULT_SSL_ROOTS_FILE_PATH.
3. Failing all of those: the system trust store, the roots bundled with gRPC, and — on macOS — certificates installed in the admin keychain.

That last point is worth knowing. grpcio ships its own root bundle and does not consult the OS store, and Python’s ssl module cannot see the macOS keychain either — so a corporate root installed the normal way is invisible to both. The client reads it explicitly, which is why “works in the browser, fails in Python” does not happen here.

Behind a TLS-inspecting proxy or a private CA, point it at your bundle:

client = QueryClient(workspace_name="my-team", ca_bundle="/etc/ssl/certs/corp-roots.pem")

An http:// endpoint connects insecurely, with no TLS at all — for local development against a stack from development/e2e_up.sh, not for anything else.

Lifetime

The client holds a gRPC channel. It is safe to keep one for the life of a notebook or a script, and there is no connection pool to tune. Close it when you are done with it:

client.close()

Or let the process exit, which closes the channel with it.