Scripting reference

The connections are exposed as system.cognidata.graphql.*, available from both gateway scripts (tag events, gateway timer/event scripts, Perspective session/component event scripts) and the Designer (e.g. the Script Console).

The work always runs on the gateway — Designer calls are forwarded over module RPC — so connection records and credentials stay server-side. The functions are registered in the gateway and designer scopes; this module has no Vision client scope.

Table of contents

Summary
query
listConnections
testConnection
Error handling
- Messages you may see
Troubleshooting

Summary

Function	Returns
`query(connection, query, [variables], [operationName], [timeoutMs])`	Response dict (typically `data` and/or `errors`).
`listConnections()`	List of enabled connection names.
`testConnection(connection)`	Dict with `connection`, `endpoint`, `ok`, and either `data` or `error`.

query

system.cognidata.graphql.query(connection, query, variables=None, operationName=None, timeoutMs=None)

Execute a GraphQL query or mutation against a configured connection. All parameters can be passed positionally or as keyword arguments.

Parameter	Type	Required	Notes
`connection`	`str`	✓	Name of a configured, enabled connection. Case-sensitive.
`query`	`str`	✓	The GraphQL document — a query or a mutation.
`variables`	`dict`		Serialized to a JSON object. Must be a dictionary.
`operationName`	`str`		Required only when the document defines multiple named operations.
`timeoutMs`	`int`		Overrides the connection’s timeout for this call. Only applied when greater than `0`; otherwise the connection setting (default `30000`) is used.

Returns the parsed JSON response as an ordinary Python dictionary — typically with data and/or errors keys.

result = system.cognidata.graphql.query(
    "warehouse-api",
    "query($code: ID!) { country(code: $code) { name capital } }",
    variables={"code": "US"},
)
country = result["data"]["country"]   # {'name': 'United States', 'capital': 'Washington D.C.'}

Mutations use the same function — just pass a mutation document:

system.cognidata.graphql.query("warehouse-api", "mutation { ping }")

listConnections

system.cognidata.graphql.listConnections()

Returns the names of all enabled connections. Takes no arguments. Disabled connections are omitted.

system.cognidata.graphql.listConnections()   # -> ['countries', 'warehouse-api', ...]

testConnection

system.cognidata.graphql.testConnection(connection)

Probes a connection with a lightweight { __typename } query — the same probe the background heartbeat uses, but on demand.

status = system.cognidata.graphql.testConnection("countries")
# {'connection': 'countries', 'endpoint': 'https://countries.trevorblades.com',
#  'ok': True, 'data': {'__typename': 'Query'}}

Key	Notes
`connection`	The name you passed in.
`endpoint`	The configured endpoint URL.
`ok`	`True` when the endpoint answered without GraphQL errors.
`data`	Present on success — the probe’s response.
`error`	Present instead of `data` on failure — the reason.

Error handling

Failures surface in two different ways, so handle them differently:

Failure	How it shows up
Transport / config / non-2xx HTTP — unknown connection name, disabled connection, endpoint down, timeout, auth rejected (401/403)	Raises `ValueError`
GraphQL execution errors — unknown field, bad arguments	Returned in the response dict under `errors`; `data` may be partial or absent

try:
    result = system.cognidata.graphql.query("countries", '{ country(code: "CA") { bogusField } }')
    if "errors" in result:
        print "GraphQL errors:", result["errors"]
    else:
        print result["data"]
except ValueError as e:
    print "Call failed:", e

Messages you may see

Message	Cause
`query() requires a 'connection' name.`	`connection` was empty or whitespace.
`query() requires a 'query' string.`	`query` was empty or whitespace.
`No GraphQL connection named 'x'.`	No saved connection with that name (names are case-sensitive).
`GraphQL connection 'x' is disabled.`	The record exists but Enabled is cleared.
`GraphQL variables must be a JSON object/dictionary.`	`variables` was passed something other than a dict.
`GraphQL request to 'x' timed out after 30000ms.`	Endpoint slow or unreachable.
`GraphQL endpoint 'x' returned HTTP 401` (or `403`)	Auth rejected — recheck Auth Type and credentials.

Troubleshooting

Symptom	Likely cause / fix
`ValueError: No GraphQL connection named 'x'.`	The name doesn’t match a saved connection (names are case-sensitive).
`ValueError: GraphQL connection 'x' is disabled.`	Enable it on the config page.
`ValueError: ... timed out after 30000ms.`	Raise Timeout (ms) on the connection, or check the network path from the gateway (not your workstation).
`ValueError: ... returned HTTP 401` (or 403)	Auth is wrong — recheck Auth Type and credentials.
`errors` present in the result	Your document is invalid for that schema — check field and argument names.
Status column shows ⚪	Connection is disabled, or hasn’t been probed yet.
`AttributeError` on `system.cognidata`	The module isn’t installed or isn’t Running, or you’re in a Vision client (unsupported scope).
Works in Designer but not in a gateway script	Check the gateway logs — the call runs gateway-side in both cases, so this usually points at a scope/permission issue in the calling script rather than the connection.