Go SDK Reference

Installation

The Triggerware Go SDK is available on GitHub:

go get github.com/triggerware/go-client

Connecting to Triggerware

Connect to a local Triggerware instance over TCP:

import tw "github.com/triggerware/triggerware-go"

client, err := tw.ConnectTCP("localhost:5221")
if err != nil {
  log.Fatal(err)
}
defer client.Close()

Client Options

After connecting, you can set defaults that apply to All subsequent queries:

Field	Type	Description	Default
`DefaultFetchSize`	`*int`	Max rows per batch fetch	`nil` (no limit)
`DefaultTimeout`	`*float64`	Timeout in seconds per query operation	`nil` (no limit)

fetchSize := 100
client.DefaultFetchSize = &fetchSize

timeout := 5.0
client.DefaultTimeout = &timeout

Queries

Construct queries with the SQL or FOL helpers. Both default to the "DEMO" schema; pass an optional second argument to override it.

q := tw.SQL("SELECT name, email FROM contacts WHERE region = 'US'")

// With explicit schema
q := tw.SQL("SELECT * FROM users", "MY_SCHEMA")

// FOL query
q := tw.FOL("((x) s.t. (users x))", "MY_PACKAGE")

Restrictions

Pass a QueryRestriction to cap rows or set a timeout for a single execution. Pass nil to use client defaults.

limit := 50
r := &tw.QueryRestriction{RowLimit: &limit}

rs, err := client.ExecuteQuery(q, r)

Executing Queries

ExecuteQuery runs a query and returns a ResultSet that streams rows lazily.

rs, err := client.ExecuteQuery(tw.SQL("SELECT name, age FROM people"), nil)
if err != nil {
  log.Fatal(err)
}

for {
  row, err := rs.Next()
  if err == io.EOF {
      break
  }
  if err != nil {
      log.Fatal(err)
  }
  fmt.Println(row)
}

Validating Queries

Check a query for errors without executing it:

err := client.ValidateQuery(tw.SQL("SELECT * FROM nonexistent"))
if err != nil {
  fmt.Println(err) // "invalid query: ..."
}

ResultSet

ResultSet is returned by ExecuteQuery. Rows are fetched from the server in batches as needed.

Method / Field	Description
`Next() (Row, error)`	Returns the next row. Returns `io.EOF` when exhausted.
`Pull(n int) ([]Row, error)`	Fetch up to `n` rows. Returns fewer if the result set is exhausted.
`Signature`	Column metadata from the server.

Row is []any — a slice of values whose types correspond to the query’s output signature.

// Fetch exactly 10 rows
rows, err := rs.Pull(10)

// Iterate through the rest
for {
  row, err := rs.Next()
  if err == io.EOF {
      break
  }
  if err != nil {
      log.Fatal(err)
  }
  fmt.Println(row)
}

Connectors

Manage connectors on the server to expose external data sources as virtual tables.

// Activate a connector
err := client.ActivateConnector("salesforce", map[string]any{"api_key": "..."})

// List active connectors
names, err := client.ListActiveConnectors()
fmt.Println(names) // ["salesforce", "zendesk"]

// Deactivate a connector
err = client.DeactivateConnector("salesforce")

Method	Description
`ActivateConnector(name string, jsonData any) error`	Load and activate a named connector. `jsonData` is passed to the connector on initialization.
`DeactivateConnector(name string) error`	Deactivate a connector and drop its virtual tables.
`ListActiveConnectors() ([]string, error)`	Returns the names of all currently active connectors.

Connection Lifecycle

Method	Description
`Close()`	Closes the underlying TCP connection.
`IsClosed() bool`	Reports whether the connection has been closed.
`Wait()`	Blocks until the connection is closed. Useful for long-running processes.

Errors

Type	Returned when
`InvalidQueryError`	The server rejects a query as syntactically invalid or referencing nonexistent tables/columns.

All other server-level errors are returned as the underlying jsonrpc.RPCError.