Globals

⚠️ Only available in EdgeDB 2.0 or later.

Schemas can contain scalar-typed global variables.

global current_user_id -> uuid;

These provide a useful mechanism for specifying session-level data that can be referenced in queries with the global keyword.

select User {
  id,
  posts: { title, content }
}
filter .id = global current_user_id;

As in the example above, this is particularly useful for representing the notion of a session or “current user”.

Setting global variables

Global variables are set when initializing a client. The exact API depends on which client library you’re using.

TypeScript

Python

Go

import createClient from 'edgedb';
const baseClient = createClient()
const clientWithGlobals = baseClient.withGlobals({
  current_user_id: '2141a5b4-5634-4ccc-b835-437863534c51',
});
await clientWithGlobals.query(`select global current_user_id;`);

from edgedb import create_client
client = create_client().with_globals({
    'current_user_id': '580cc652-8ab8-4a20-8db9-4c79a4b1fd81'
})
result = client.query("""
    select global current_user_id;
""")
print(result)

package main
import (
  "context"
  "fmt"
  "log"
  "github.com/edgedb/edgedb-go"
)
func main() {
  ctx := context.Background()
  client, err := edgedb.CreateClient(ctx, edgedb.Options{})
  if err != nil {
    log.Fatal(err)
  }
  defer client.Close()
  id, err := edgedb.ParseUUID("2141a5b4-5634-4ccc-b835-437863534c51")
  if err != nil {
    log.Fatal(err)
  }
  var result edgedb.UUID
  err = client.
    WithGlobals(map[string]interface{}{"current_user": id}).
    QuerySingle(ctx, "SELECT global current_user;", &result)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(result)
}

The .withGlobals/.with_globals method returns a new Client instance that stores the provided globals and sends them along with all future queries.

Cardinality

Global variables can be marked required; in this case, you must specify a default value.

required global one_string -> str {
  default := "Hi Mom!"
};

Computed globals

Global variables can also be computed. The value of computed globals are dynamically computed when they are referenced in queries.

required global random_global := datetime_of_transaction();

The provided expression will be computed at the start of each query in which the global is referenced. There’s no need to provide an explicit type; the type is inferred from the computed expression.

Computed globals are not subject to the same constraints as non-computed ones; specifically, they can be object-typed and have a multi cardinality.

global current_user_id -> uuid;
# object-typed global
global current_user := (
  select User filter .id = global current_user_id
);
# multi global
global current_user_friends := (global current_user).friends;

Usage in schema

Unlike query parameters, globals can be referenced inside your schema declarations.

type User {
  property name -> str;
  property is_self := (.id = global current_user_id)
};

This is particularly useful when declaring access policies.

type Person {
  required property name -> str;
  access policy my_policy allow all using (.id = global current_user_id);
}

Refer to Access Policies for complete documentation.

︙