Skip to content

query-usage.md

Latest commit

 

History

History
384 lines (281 loc) · 9.99 KB

query-usage.md

File metadata and controls

384 lines (281 loc) · 9.99 KB
Raw

Query Usage

Arguments

The arguments supported are ids, where, orderBy , skip, and take.

Arguments are executed in that order.

Navigation fields

Navigation list and connection fields accept the same arguments. When the parent entity is loaded through a projection, ids, where and orderBy are applied inside the query, as part of the subquery that loads the collection, so the database evaluates them. skip, take and the connection paging are applied in memory to the collection that was loaded.

The arguments are evaluated in memory instead when the same navigation is selected more than once with different arguments, when the field's resolver returns something other than the projected collection, or when the parent could not be projected. In memory, string comparisons ignore case, matching the default SQL Server collation, and like supports %, _ and [].

Ids

Queries entities by id. Currently the only supported identity member (property or field) name is Id.

Supported Types

String, Guid, Double, Boolean, Float, Byte, DateTime, DateTimeOffset, Decimal, Int16, Int32, Int64, UInt16, UInt32, and UInt64.

Single

{
  entities (ids: "1")
  {
    property
  }
}

Multiple

{
  entities (ids: ["1", "2"])
  {
    property
  }
}

Where

The where argument is an input type generated for the entity, named after the CLR type: PersonWhere for Person. It has one field per mapped property, typed by the comparisons that property supports, one field per navigation, and and, or and not to compose them. Since the schema describes it, a mistyped property or a value of the wrong type is rejected at validation, and tooling can complete it.

input PersonWhere {
  and: [PersonWhere!]
  or: [PersonWhere!]
  not: PersonWhere
  id: GuidComparison
  name: StringComparison
  age: Int32Comparison
  company: CompanyWhere
  addresses: AddressCollectionWhere
}

Fields set on the same object are and'ed together.

Supported Types

String, Guid, Double, Boolean, Float, Byte, SByte, DateTime, DateOnly, TimeOnly, DateTimeOffset, Decimal, Int16, Int32, Int64, UInt16, UInt32, UInt64, and Enum.

Properties of other types, such as byte arrays and primitive collections, get no field. Values are the GraphQL scalar for the type, so a date is written as a string in ISO 8601 form, an enum as its enum value, and a number as a number.

Supported Comparisons

Each property is typed by a comparison input named after the CLR type of its values, StringComparison, Int32Comparison, DateTimeComparison, and so on. Every comparison field is optional, and the ones set are and'ed together.

  • equal
  • notEqual
  • in: The value is in the given list
  • greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual: Not on string, bool or enum properties
  • contains, startsWith, endsWith: Only on string
  • like: Only on string. Performs a SQL Like by using EF.Functions.Like
input StringComparison {
  equal: String
  notEqual: String
  in: [String]
  startsWith: String
  endsWith: String
  contains: String
  like: String
}

input Int32Comparison {
  equal: Int
  notEqual: Int
  in: [Int]
  greaterThan: Int
  greaterThanOrEqual: Int
  lessThan: Int
  lessThanOrEqual: Int
}

Single

{
  entities
  (where: {property: {equal: "the value"}})
  {
    property
  }
}
TimeOnly query
{
  timeEntities (where: {property: {equal: "10:11:00"}})
  {
    id
  }
}
DateOnly query
{
  dateEntities (where: {property: {equal: "2020-10-01"}})
  {
    id
  }
}

Where In

{
  testEntities
  (where: {property: {in: ["Value1", "Value2"]}})
  {
    property
  }
}

Multiple Expressions and Expression Grouping

Comparisons on the same property and fields on the same object are and'ed. and and or take a list of where objects, and not negates one:

{
  entities
  (where: {
    property: {startsWith: "Valu"},
    or: [
      {property: {endsWith: "ue"}},
      {property: {endsWith: "id"}}
    ]
  })
  {
    property
  }
}

The above expression written as a logical statement would be:

Property.startsWith("Valu") && (Property.endsWith("ue") || Property.endsWith("id"))

Query Negation

To negate an expression, including a group, wrap it in not:

{
  entities
  (where: {
    property: {startsWith: "Valu"},
    not: {
      or: [
        {property: {endsWith: "ue"}},
        {property: {endsWith: "id"}}
      ]
    }
  })
  {
    property
  }
}

Nested Properties

A reference navigation, owned type or complex property is a nested where object. No null checking of nested values is done; to test the navigation itself see Null.

{
  entities
  (where: {address: {street: {startsWith: "Main"}}})
  {
    property
  }
}

Querying List Members

A common query function is constraining a master set by some property of the detail list. For example to filter all orders by line items for a specific product.

Note: This only constrains the master list and doesn't affect the detail list, re-query the detail list with the same query to achieve this effect.

A collection navigation is a where object with any, all and none, each taking a where on the item type:

{
  entities
  (where: {listProperty: {any: {property: {startsWith: "Valu"}}}})
  {
    property
  }
}
  • any: At least one item matches. any: {} matches entities with at least one item.
  • all: Every item matches, including when there are no items.
  • none: No item matches.

Null

Null is compared with a null value:

{
  entities
  (where: {property: {equal: null}})
  {
    property
  }
}

An empty where, {}, applies no filter.

A reference navigation is tested with isNull, since a nested where can only constrain the members of the navigation, not the navigation itself:

{
  entities
  (where: {address: {isNull: true}})
  {
    property
  }
}

isNull: false requires the navigation to be present. A collection navigation uses none: {} and any: {} instead. isNull has no meaning at the root of a where, since there is no navigation it was reached through.

Variables

The where input types are named in the schema, so a where can be passed as a variable:

query ($where: PersonWhere)
{
  people (where: $where)
  {
    name
  }
}

OrderBy

The orderBy argument is a list of input objects generated for the entity, named after the CLR type: PersonOrderBy for Person. Each has one field per mapped property, taking ascending or descending, and one per reference navigation to order by a nested property. Each item in the list sets exactly one property; the list gives the order of the keys.

Ascending

{
  entities (orderBy: {property: ascending})
  {
    property
  }
}

Descending

{
  entities (orderBy: {property: descending})
  {
    property
  }
}

Multiple

{
  entities (orderBy: [{property: descending}, {id: ascending}])
  {
    property
  }
}

Nested Properties

{
  entities (orderBy: {parent: {property: ascending}})
  {
    property
  }
}

Take

Queryable.Take or Enumerable.Take can be used as follows:

{
  entities (take: 1)
  {
    property
  }
}

Skip

Queryable.Skip or Enumerable.Skip can be used as follows:

{
  entities (skip: 1)
  {
    property
  }
}