Installation

The query SDK lives in the metrana package, behind the query extra:

pip install 'metrana[query]'

Requires Python 3.10+, same as the base package.

Why an extra

metrana.query is pure Python, but it needs an analysis stack the logger does not:

Dependency	For
grpcio	the transport
protobuf + metrana-protobuf	the wire types
numpy	the numeric assembly of results
pandas	the DataFrame results

Keeping them optional means a training image that only calls metrana.log(...) never installs pandas. The subpackage is also not imported from the metrana root, so importing the logger never loads any of it.

Importing without the extra fails immediately, with the fix in the message:

>>> import metrana.query
ImportError: metrana.query requires the optional query dependencies (grpcio, protobuf,
metrana-protobuf, numpy, pandas). Install them with: pip install 'metrana[query]'

Connecting

from metrana.query import QueryClient

client = QueryClient(
    workspace_name="my-team",
    project_name="my-project",   # a default; every method can override it
    api_key="...",               # or METRANA_API_KEY
)

Every argument falls back to an environment variable, so a configured shell needs none of them:

Variable	Argument
METRANA_API_KEY	api_key
METRANA_WORKSPACE	workspace_name
METRANA_PROJECT	project_name
METRANA_QUERY_API_URL	query_url

query_url also falls back to query_api_url from metrana.init() before the environment variable, so a process that logs and reads needs the endpoint only once — see Service endpoints.

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

Construction connects eagerly and fails fast on an unreachable endpoint (connect_timeout, default 10 s) rather than deferring the error to your first query. See Client configuration for the full argument list, timeouts, and TLS trust roots.