Tutorial: from zero to your first query

This walks you from a freshly installed module to a working query, using the free, no-auth public Countries GraphQL API so you can follow along without any credentials.

Table of contents

• Prerequisites
• Step 1 — Add a connection
• Step 2 — Confirm it’s reachable
• Step 3 — Run your first query
• Step 4 — Pass variables
• Step 5 — Handle the two kinds of failure
• Step 6 — Run a mutation
• Step 7 — Use it in a real script
• Next steps

---

Prerequisites

• The Cognidata GraphQL module is installed and Running (Gateway → Config → Modules).
• You can open the Designer Script Console (Tools → Script Console). It’s the quickest place to experiment — Designer calls are forwarded to the gateway automatically, so everything behaves exactly as it would in a gateway script.

Step 1 — Add a connection

In the Gateway web UI, go to Config → Cognidata → GraphQL Connections, create a new connection, and fill in:

Field	Value
Name	countries
Endpoint URL	https://countries.trevorblades.com
Auth Type	NONE
Enabled	✓

Leave the rest at their defaults (Timeout 30000 ms, Verify TLS on) and save.

Step 2 — Confirm it’s reachable

Back on the connections table, the Connection Status column should turn 🟢 Online within ~30s (a background heartbeat probes { __typename } on a schedule). You can also probe on demand from the Script Console:

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

ok is True when the endpoint answered without GraphQL errors.

Step 3 — Run your first query

The response comes back as an ordinary Python dictionary — the parsed JSON the endpoint returned, with data and/or errors keys.

result = system.cognidata.graphql.query(
    "countries",
    '{ country(code: "CA") { name capital currency } }',
)
country = result["data"]["country"]
# {'name': 'Canada', 'capital': 'Ottawa', 'currency': 'CAD'}

Step 4 — Pass variables

Prefer variables over string-building your query — it’s safer and reusable. variables must be a dictionary (it’s serialized to a JSON object); passing anything else raises a ValueError.

QUERY = "query($code: ID!) { country(code: $code) { name emoji } }"

for code in ["US", "JP", "BR"]:
    country = system.cognidata.graphql.query("countries", QUERY, variables={"code": code})["data"]["country"]
    print code, country["name"], country["emoji"]   # US United States 🇺🇸  ...

The examples here use Jython 2 print statement syntax, matching Ignition’s Script Console.

You can also fetch a whole collection in one call:

result = system.cognidata.graphql.query(
    "countries",
    '{ continent(code: "AF") { name countries { code name } } }',
)
africa = result["data"]["continent"]["countries"]   # [{'code': 'AO', 'name': 'Angola'}, ...]

Step 5 — Handle the two kinds of failure

They surface differently, 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 — wrap the call in try/except.
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"]   # the endpoint rejected the document
    else:
        print result["data"]
except ValueError as e:
    print "Call failed:", e                          # couldn't reach/parse the endpoint

Step 6 — Run a mutation

Mutations use the same query() function — just pass a mutation document (the Countries API is read-only, so point this at your own endpoint):

system.cognidata.graphql.query(
    "warehouse-api",
    "mutation($id: ID!) { archiveOrder(id: $id) { id status } }",
    variables={"id": "1007"},
)

Step 7 — Use it in a real script

The functions live in both the gateway and designer scopes, so the same call works in a gateway tag change script, a gateway timer script, a Perspective session/component event, or the Designer. For example, a Perspective button’s onActionPerformed handler that loads data into a custom property:

def runAction(self, event):
    data = system.cognidata.graphql.query("countries", "{ countries { code name } }")["data"]
    self.view.custom.countries = data["countries"]

Whatever the scope, the request executes on the gateway, so endpoints and credentials never leave the server.

Next steps

• Full signatures and return shapes → Scripting reference
• Auth modes, custom headers, TLS and status → Connections