Basics​

For the purposes of this section we will consider the default module containing the following schema:


1. type Author {
2. property name -> str;
3. }

5. type Book {
6. # to make the examples simpler only the title is
7. # a required property
8. required property title -> str;
9. property synopsis -> str;
10. link author -> Author;
11. property isbn -> str {
12. constraint max_len_value(10);
13. }
14. }

From the schema above EdgeDB will expose to GraphQL:

  • Object types: Author and Book
  • scalars String and ID

In addition to this the Query will have 2 fields: Author, and Book to query these types respectively.

Queries​

Consider this example:

GraphQL EdgeQL equivalent
Basics - 图1Copy 1. { 2. Book { 3. title 4. synopsis 5. author { 6. name 7. } 8. } 9. } Basics - 图2Copy 1. select 2. Book { 3. title, 4. synopsis, 5. author: { 6. name 7. } 8. };

The top-level field of the GraphQL query must be a valid name of an object type or an expression alias of something returning an object type. Nested fields must be valid links or properties.

There are some specific conventions as to how arguments in GraphQL queries are used to allow filtering, ordering, and paginating data.

Filtering​

Filtering the retrieved data is done by specifying a filter argument. The filter argument is customized to each specific type based on the available fields. In case of the sample schema, here are the specifications for available filter arguments for querying Book:


1. # this is Book-specific
2. input FilterBook {
3. # basic boolean operators that combine conditions
4. and: [FilterBook!]
5. or: [FilterBook!]
6. not: FilterBook

8. # fields available for filtering (properties in EdgeQL)
9. title: FilterString
10. synopsis: FilterString
11. isbn: FilterString
12. author: NestedFilterAuthor
13. }

15. # this is Author-specific
16. input NestedFilterAuthor {
17. # instead of boolean operations, "exists" check is available
18. # for links
19. exists: Boolean

21. # fields available for filtering (properties in EdgeQL)
22. name: FilterString
23. }

25. # this is generic
26. input FilterString {
27. # "exists" check is available for every property, too
28. exists: Boolean

30. # equality
31. eq: String
32. neq: String

34. # lexicographical comparison
35. gt: String
36. gte: String
37. lt: String
38. lte: String

40. # other useful operations
41. like: String
42. ilike: String
43. }

Here are some examples of using a filter:

GraphQL EdgeQL equivalent
Basics - 图3Copy 1. { 2. Book( 3. filter: { 4. title: { 5. eq: “Spam” 6. } 7. } 8. ) { 9. title 10. synopsis 11. } 12. } Basics - 图4Copy 1. select 2. Book { 3. title, 4. synopsis 5. } 6. filter 7. Book.title = ‘Spam’;
Basics - 图5Copy 1. { 2. Book( 3. filter: { 4. author: { 5. name: { 6. eq: 7. “Lewis Carroll” 8. } 9. } 10. } 11. ) { 12. title 13. synopsis 14. } 15. } Basics - 图6Copy 1. select 2. Book { 3. title, 4. synopsis 5. } 6. filter 7. Book.author.name = 8. ‘Lewis Carroll’;

It is legal to provide multiple input fields in the same input object. They are all implicitly combined using a logical conjunction. For example:

GraphQL EdgeQL equivalent
Basics - 图7Copy 1. { 2. Book( 3. filter: { 4. title: { 5. gte: “m”, 6. lt: “o” 7. } 8. } 9. ) { 10. title 11. } 12. } Basics - 图8Copy 1. select 2. Book { 3. title, 4. } 5. filter 6. Book.title >= ‘m’ 7. and 8. Book.title < ‘o’;

It is possible to search for books that don’t specify the author for some reason:

GraphQL EdgeQL equivalent
Basics - 图9Copy 1. { 2. Book( 3. filter: { 4. author: { 5. exists: false 6. } 7. } 8. ) { 9. id 10. title 11. } 12. } Basics - 图10Copy 1. select 2. Book { 3. id, 4. title 5. } 6. filter 7. not exists 8. Book.author;

Ordering​

Ordering the retrieved data is done by specifying an order argument. The order argument is customized to each specific type based on the available fields, much like the filter. In case of the sample schema, here are the specifications for the available filter arguments:


1. # this is Author-specific
2. input OrderAuthor {
3. # fields available for ordering (properties in EdgeQL)
4. name: Ordering
5. }

7. # this is Book-specific
8. input OrderBook {
9. # fields available for ordering (properties in EdgeQL)
10. title: Ordering
11. synopsis: Ordering
12. isbn: Ordering
13. }

15. # this is generic
16. input Ordering {
17. dir: directionEnum
18. nulls: nullsOrderingEnum
19. }

21. enum directionEnum {
22. ASC
23. DESC
24. }

26. enum nullsOrderingEnum {
27. SMALLEST    # null < any other value
28. BIGGEST     # null > any other value
29. }

If the value of nulls is not specified it is assumed to be SMALLEST.

GraphQL EdgeQL equivalent
Basics - 图11Copy 1. { 2. Author( 3. order: { 4. name: { 5. dir: ASC, 6. nulls: BIGGEST 7. } 8. } 9. ) { 10. name 11. } 12. } Basics - 图12Copy 1. select 2. Author { 3. name, 4. } 5. order by 6. Author.name asc 7. empty last;

Paginating​

Paginating the retrieved data is done by providing one or more of the following arguments: first, last, before, and after. The pagination works in a similar way to Relay Connections. In case of the sample schema, here are the specifications for the available filter arguments:


1. # a relevant Query definition snippet
2. type Query {
3. Author(
4. filter: FilterAuthor,
5. order: OrderAuthor,

7. after: String,
8. before: String,
9. first: Int,
10. last: Int,
11. ): [Author!]

13. # ... other Query fields
14. }

The after and before strings are, in fact, string representations of numeric indices under the particular filter and ordering (starting at “0”). This makes the usage fairly intuitive even without having Relay Connection edges and cursors.

The objects corresponding to the indices specified by before or after are not included.

GraphQL EdgeQL equivalent
Basics - 图13Copy 1. { 2. Author( 3. order: { 4. name: { 5. dir: ASC 6. } 7. }, 8. first: 10 9. ) { 10. name 11. } 12. } Basics - 图14Copy 1. select 2. Author { 3. name, 4. } 5. order by 6. Author.name asc 7. limit 10;
Basics - 图15Copy 1. { 2. Author( 3. order: { 4. name: { 5. dir: ASC 6. } 7. }, 8. after: “19”, 9. first: 10 10. ) { 11. name 12. } 13. } Basics - 图16Copy 1. select 2. Author { 3. name, 4. } 5. order by 6. Author.name asc 7. offset 20 limit 10;
Basics - 图17Copy 1. { 2. Author( 3. order: { 4. name: { 5. dir: ASC 6. } 7. }, 8. after: “19”, 9. before: “30” 10. ) { 11. name 12. } 13. } Basics - 图18Copy 1. select 2. Author { 3. name, 4. } 5. order by 6. Author.name asc 7. offset 20 limit 10;

Variables​

It is possible to use variables within GraphQL queries. They are mapped to variables in EdgeQL.

GraphQL EdgeQL equivalent
Basics - 图19Copy 1. query ($title: String!) { 2. Book( 3. filter: { 4. title: { 5. eq: $title 6. } 7. } 8. ) { 9. title 10. synopsis 11. } 12. } Basics - 图20Copy 1. select 2. Book { 3. title, 4. synopsis, 5. } 6. filter 7. .title = $title;