Client Configuration

Tutorial

Client Configuration

Configure the SDK for development, staging, and production environments

20 min Advanced

ClientConfigurationEnvironmentSSLProxy

What You'll Learn

• Environment-based configuration - Use from_env() to configure the client from environment variables
• Timeouts and retries - Set custom timeouts and retry policies for production
• SSL and proxy - Configure SSL verification and proxy for corporate networks
• Context managers - Use with blocks for automatic resource cleanup
• Connection behavior - Understand connection pooling and HTTP client behavior
• Quick start vs explicit setup - Use quick_start() for prototyping vs explicit setup for production

1

Setup

Connect to the platform

# Cell 1 — Parameters
USERNAME = "_FILL_ME_IN_"  # Set your email before running

# Cell 2 — Connect
from graph_olap import GraphOLAPClient
client = GraphOLAPClient(username=USERNAME)

# Cell 3 — Provision
from notebook_setup import provision
personas, conn = provision(USERNAME)
analyst = personas["analyst"]
admin = personas["admin"]
ops = personas["ops"]
client = analyst

print(f"Connected | API: {client._config.api_url}")
print(f"Timeout: {client._config.timeout}s | Username: {client._config.username}")

2

Direct Construction

Understand GraphOLAPClient.__init__() parameters

Since ADR-126, username is the only required parameter. All other settings are resolved from environment variables with baked-in defaults:

Parameter	Type	Default	Description
username	str	required	Username for X-Username header
api_url	str | None	env / baked-in	Base URL (keyword-only, from GRAPH_OLAP_API_URL)
use_case_id	str | None	env / baked-in	Use case ID (from GRAPH_OLAP_USE_CASE_ID)
proxy	str | None	None	HTTP proxy URL
verify	bool	True	SSL certificate verification
timeout	float	30.0	Request timeout in seconds
max_retries	int	3	Max retry attempts

The sentinel value "_FILL_ME_IN_" is rejected with a clear ValueError.

# Direct construction with explicit parameters
# (illustration — the shared client is already connected)
print("GraphOLAPClient constructor parameters:")
print(f"  api_url:     {client._config.api_url}")
print(f"  username:    {client._config.username}")
print(f"  timeout:     {client._config.timeout}s")
print(f"  max_retries: {client._config.max_retries}")
print(f"  verify:      {client._config.verify}")

3

Environment-Based Configuration

Use from_env() and GRAPH_OLAP_* environment variables

GraphOLAPClient.from_env() reads configuration from environment variables, making it ideal for deployment scripts and CI/CD pipelines. Explicit keyword arguments override any environment variable values. Extra **kwargs are forwarded to __init__().

Since ADR-126, from_env() no longer raises ValueError when GRAPH_OLAP_API_URL is unset — the baked-in default is used instead.

import os

# Show which environment variables from_env() reads
env_vars = [
    "GRAPH_OLAP_API_URL",
    "GRAPH_OLAP_USERNAME",
    "GRAPH_OLAP_USE_CASE_ID",
    "GRAPH_OLAP_PROXY",
    "GRAPH_OLAP_SSL_VERIFY",
]

print("Environment variables for from_env():")
for var in env_vars:
    value = os.environ.get(var, "(not set)")
    print(f"  {var}: {value}")

# from_env() reads these automatically:
# client = GraphOLAPClient.from_env()
# client = GraphOLAPClient.from_env(timeout=60.0)  # override timeout
print("\nfrom_env() is recommended for scripts and applications")

4

Environment Profiles

Three configurations for development, staging, and production

Different environments have different priorities. Development favours fast feedback; staging mirrors production behind a corporate proxy; production requires strict verification and resilience.

# Profile 1: Local development (relaxed settings)
# dev_client = GraphOLAPClient(
#     username="developer@local",
#     api_url="http://localhost:8080",  # override the default
#     timeout=60.0,       # Generous timeout for debugging
#     max_retries=1,       # Fail fast during development
#     verify=False,        # No SSL for local
# )

print("Development profile:")
print("  timeout=60s, max_retries=1, verify=False")
print("  Optimized for fast feedback during development")

# Profile 2: Staging (corporate proxy + custom SSL)
# staging_client = GraphOLAPClient(
#     username="[email protected]",
#     api_url="https://staging.graph-olap.internal",
#     proxy="http://proxy.corp.com:8080",
#     verify=True,
#     timeout=30.0,
#     max_retries=3,
# )

print("Staging profile:")
print("  proxy=http://proxy.corp.com:8080, verify=True")
print("  Routes traffic through corporate proxy")

# Profile 3: Production (strict, tuned)
# prod_client = GraphOLAPClient.from_env(
#     timeout=15.0,        # Tight timeout for responsive apps
#     max_retries=5,        # More retries for resilience
# )

print("Production profile:")
print("  timeout=15s, max_retries=5, verify=True (default)")
print("  Use from_env() so credentials stay in environment")

5

Context Manager Pattern

Automatic resource cleanup with with blocks

The client implements the context manager protocol. Using a with block guarantees that close() is called when the block exits, even if an exception is raised. This releases the underlying HTTP connection pool.

# Context manager ensures close() is called automatically
with GraphOLAPClient(username=client._config.username) as temp_client:
    health = temp_client.health.check()
    print(f"Health check: {health.status}")
    mappings = temp_client.mappings.list(limit=1)
    print(f"Mappings: {mappings.total}")
# temp_client.close() called automatically here

print("Client closed — resources released")

6

Quick Start

Rapid prototyping with quick_start()

quick_start() combines instance creation and connection into a single call. It creates an instance from a mapping, waits for it to become ready, and returns an InstanceConnection object ready for queries.

For production code, prefer the explicit two-step flow (create_and_wait then connect) which gives you full control over instance lifecycle and error handling.

# quick_start() creates an instance and returns a connection in one call
# Perfect for scripts and one-off analyses:
#
#   conn = client.quick_start(
#       mapping_id=42,
#       wrapper_type="ryugraph",
#       instance_name="analysis-run",
#       wait_timeout=900,
#   )
#   result = conn.query("MATCH (n) RETURN count(n)")
#   conn.close()

# Compare with explicit setup:
# 1. instance = client.instances.create_and_wait(mapping_id=42, ...)
# 2. conn = client.instances.connect(instance.id)
# 3. result = conn.query(...)
# 4. conn.close()

print("quick_start() = create_and_wait() + connect() in one call")
print("Use it for prototyping; use explicit setup for production control")

7

Resource Attributes

Overview of all client resource managers

The client exposes domain-specific resource managers as attributes. Each manager provides CRUD operations for its resource type.

resources = {
    "mappings":  client.mappings,
    "instances": client.instances,
    "favorites": client.favorites,
    "schema":    client.schema,
    "ops":       client.ops,
    "admin":     client.admin,
    "health":    client.health,
    "users":     client.users,
}

print("Client resource attributes:")
for name, resource in resources.items():
    print(f"  client.{name:10s} -> {type(resource).__name__}")

Key Takeaways

• username is the only required parameter -- api_url and use_case_id have baked-in defaults (ADR-126)
• Use from_env() in production -- keeps credentials in environment variables
• Set timeout and max_retries based on your environment (generous for dev, tight for prod)
• Use proxy and verify=False only behind corporate proxies or in development
• Always close clients via with block or explicit close() call
• quick_start() is ideal for prototyping; explicit setup gives more control in production