Light
Dark
System

Select

The full power of the EdgeQL select statement is available as a top-level e.select function. All queries on this page assume the Netflix schema described on the Objects page.

Any scalar expression be passed into e.select, though it’s often unnecessary, since expressions are runable without being wrapped by e.select.

Copy
e.select(e.str('Hello world'));
// select 1234;

e.select(e.op(e.int64(2), '+', e.int64(2)));
// select 2 + 2;

Select a free object by passing an object into e.select

Copy
e.select({
  name: e.str("Name"),
  number: e.int64(1234),
  movies: e.Movie,
});
/* select {
  name := "Name",
  number := 1234,
  movies := Movie
} */

As in EdgeQL, selecting an set of objects without a shape will return their id property only. This is reflected in the TypeScript type of the result.

Copy
const query = e.select(e.Movie);
// select Movie;

const result = await query.run(client);
// {id:string}[]

To specify a shape, pass a function as the second argument. This function should return an object that specifies which properties to include in the result. This roughly corresponds to a shape in EdgeQL.

Copy
const query = e.select(e.Movie, ()=>({
  id: true,
  title: true,
  release_year: true,
}));
/*
  select Movie {
    id,
    title,
    release_year
  }
*/

Note that the type of the query result is properly inferred from the shape. This is true for all queries on this page.

Copy
const result = await query.run(client);
/* {
  id: string;
  title: string;
  release_year: number | undefined;
}[] */

As you can see, the type of release_year is number | undefined since it’s an optional property, whereas id and title are required.

Passing a boolean value (as opposed to a true literal), which will make the property optional. Passing false will exclude that property.

Copy
e.select(e.Movie, movie => ({
  id: true,
  title: Math.random() > 0.5,
  release_year: false,
}));

const result = await query.run(client);
// {id: string; title: string | undefined; release_year: never}[]

For convenience, the query builder provides a shorthand for selecting all properties of a given object.

Copy
e.select(e.Movie, movie => ({
  ...e.Movie['*']
}));

const result = await query.run(client);
// {id: string; title: string; release_year: number | null}[]

This * property is just a strongly-typed, plain object:

e.Movie['*'];
// => {id: true, title: true, release_year: true}

As in EdgeQL, shapes can be nested to fetch deeply related objects.

Copy
const query = e.select(e.Movie, () => ({
  id: true,
  title: true,
  actors: {
    name: true
  }
}));

const result = await query.run(client);
/* {
  id: string;
  title: string;
  actors: { name: string }[]
}[] */

In EdgeQL, a select statement introduces a new scope; within the clauses of a select statement, you can refer to fields of the elements being selected using leading dot notation.

Copy
select Movie { id, title }
filter .title = "The Avengers";

Here, .title is shorthand for the title property of the selected Movie elements. All properties/links on the Movie type can be referenced using this shorthand anywhere in the select expression. In other words, the select expression is scoped to the Movie type.

To represent this scoping in the query builder, we use function scoping. This is a powerful pattern that makes it painless to represent filters, ordering, computed fields, and other expressions. Let’s see it in action.

To add a filtering clause, just include a filter key in the returned params object. This should correspond to a boolean expression.

Copy
e.select(e.Movie, movie => ({
  id: true,
  title: true,
  filter: e.op(movie.title, 'ilike', "The Matrix%")
}));
/*
  select Movie {
    id,
    title
  } filter .title ilike "The Matrix%"
*/

Since filter is a reserved keyword in EdgeDB, there is minimal danger of conflicting with a property or link named filter. All shapes can contain filter clauses, even nested ones.

As with filter, you can pass a value with the special order_by key. To simply order by a property:

Copy
e.select(e.Movie, movie => ({
  order_by: movie.title,
}));

Unlike filter, order_by is not a reserved word in EdgeDB. Using order_by as a link or property name will create a naming conflict and likely cause bugs.

The order_by key can correspond to an arbitrary expression.

Copy
// order by length of title
e.select(e.Movie, movie => ({
  order_by: e.len(movie.title),
}));
/*
  select Movie
  order by len(.title)
*/

// order by number of actors
e.select(e.Movie, movie => ({
  order_by: e.count(movie.actors),
}));
/*
  select Movie
  order by count(.actors)
*/

You can customize the sort direction and empty-handling behavior by passing an object into order_by.

Copy
e.select(e.Movie, movie => ({
  order_by: {
    expression: movie.title,
    direction: e.DESC,
    empty: e.EMPTY_FIRST,
  },
}));
/*
  select Movie
  order by .title desc empty first
*/

Order direction

e.DESC e.ASC

Empty handling

e.EMPTY_FIRST e.EMPTY_LAST

Pass an array of objects to do multiple ordering.

Copy
e.select(e.Movie, movie => ({
  title: true,
  order_by: [
    {
      expression: movie.title,
      direction: e.DESC,
    },
    {
      expression: e.count(movie.actors),
      direction: e.ASC,
      empty: e.EMPTY_LAST,
    },
  ],
}));

To add a computed field, just add it to the returned shape alongside the other elements. All reflected functions are typesafe, so the output type

Copy
const query = e.select(e.Movie, movie => ({
  title: true,
  uppercase_title: e.str_upper(movie.title),
  title_length: e.len(movie.title),
}));

const result = await query.run(client);
/* =>
  [
    {
      title:"Iron Man",
      uppercase_title: "IRON MAN",
      title_length: 8
    },
    ...
  ]
*/
// {name: string; uppercase_title: string, title_length: number}[]

Computed fields can “override” an actual link/property as long as the type signatures agree.

Copy
e.select(e.Movie, movie => ({
  title: e.str_upper(movie.title), // this works
  release_year: e.str("2012"), // TypeError

  // you can override links too
  actors: e.Person,
}));

EdgeQL supports polymorphic queries using the [is type] prefix.

Copy
select Content {
  title,
  [is Movie].release_year,
  [is TVShow].num_seasons
}

In the query builder, this is represented with the e.is function.

Copy
e.select(e.Content, content => ({
  title: true,
  ...e.is(e.Movie, { release_year: true }),
  ...e.is(e.TVShow, { num_seasons: true }),
}));

const result = await query.run(client);
/* {
  title: string;
  release_year: number | null;
  num_seasons: number | null;
}[] */

The release_year and num_seasons properties are nullable to reflect the fact that they will only occur in certain objects.

Sometimes you need to “detach” a set reference from the current scope. (Read the reference docs for details.) You can achieve this in the query builder with the top-level e.detached function.

Copy
const query = e.select(e.Person, (outer) => ({
  name: true,
  castmates: e.select(e.detached(e.Person), (inner) => ({
    name: true,
    filter: e.op(outer.acted_in, 'in', inner.acted_in)
  })),
}));
/*
  with outer := Person
  select Person {
    name,
    castmates := (
      select detached Person { name }
      filter .acted_in in Person.acted_in
    )
  }
*/
Light
Dark
System