Projection and field aliasing

Projection allows you to select the fields to be returned and is supported for Struct, Array, Set, and Document types. If you apply projection to a type that doesn’t support projection, the result is an object with the same shape as the projection request but all field values are set to null.

If a requested field doesn’t exist in the projected object, the returned field value is set to null.

Fields are returned in the order listed in the query.

Struct projection

The result of projection on a Struct returns a struct with only the requested fields extracted.

let author = {
  "firstName": "bob",
  "lastName": "cat",
  "address": {
    "street": "marbury lane",
    "number": 1452,
    "zipCode": 55555
  }
}
author {
  lastName,
  address {
    street
  }
}
{
  "lastName": "cat",
  "address": {
    "street": "marbury lane"
  }
}

Array projection

The result of projection on an array is an array with the projection applied to each element of the array:

let locations = [
    {"city": "New York", "state": "New York"},
    {"city": "Michigan City", "state": "Indiana"},
    {"city": "Seattle", "state": "Washington"},
]
locations {
    city
}
[
  {
    "city": "New York"
  },
  {
    "city": "Michigan City"
  },
  {
    "city": "Seattle"
  }
]

Set projection

The result of projection on a Set is a new Set where the field selections are applied to each element in the original Set. The result type on a Set is a Set.

For example:

Store.all() { name }
{
  data: [
    {
      name: "DC Fruits"
    },
    {
      name: "Party Supplies"
    },
    {
      name: "Foggy Bottom Market"
    }
  ]
}

Document projection

Applying projection to a document, the projected fields are extracted directly from the document. The value returned from projection on a document is a Struct.

For example:

Store.byName("Party Supplies").first() { name }
{
  name: "Party Supplies"
}

Document relationship dereferencing

When a document is nested in another document, only the id and coll fields of the nested document are stored:

Store.byName("Party Supplies").first()
  ?.update({
    stock: Product.byName("pinata").first()
  })
{
  id: "394794192088334402",
  coll: Store,
  ts: Time("2099-04-10T16:07:02.515Z"),
  name: "Party Supplies",
  address: {
    street: "7529 Capitalsaurus Court",
    city: "Washington",
    state: "DC",
    zipCode: "20002"
  },
  stock: Product("394794192093577282")
}

 

Projection is used to update the document and store a stock field.

When the stock field is referenced, using projection, the full referenced document is returned:

Store.byName("Party Supplies").first() { stock }
{
  stock: {
    id: "394794192093577282",
    coll: Product,
    ts: Time("2099-04-10T15:45:31.360Z"),
    name: "pinata",
    description: "Original Classic Donkey Pinata",
    price: 24.99,
    quantity: 40,
    store: Store("394794192088334402"),
    backorderLimit: 10,
    backordered: false
  }
}

Field aliasing

Referencing fields can be simplified when working with projected fields, including nested fields, by defining an alias using field accessors. A field alias gives you a shortcut for referencing fields and field combinations.

Example projecting a nested field:

  1. Given the following document:

    Store.byName("Party Supplies").first()
    {
  id: "394794192088334402",
  coll: Store,
  ts: Time("2099-04-10T15:45:31.360Z"),
  name: "Party Supplies",
  address: {
    street: "7529 Capitalsaurus Court",
    city: "Washington",
    state: "DC",
    zipCode: "20002"
  }
}

  2. Define an alias using dot notation to get the value of the projected field:

    Store.byName("Party Supplies").first() {
  myCity: .address.city
}
    {
  myCity: "Washington"
}

 

Example projecting multiple fields:

  1. Given the following document:

    Customer.byName("Alice", "Appleseed").first()
    {
  id: "394794192117694530",
  coll: Customer,
  ts: Time("2099-04-10T15:45:31.360Z"),
  firstName: "Alice",
  lastName: "Appleseed",
  address: {
    street: "87856 Mendota Court",
    city: "Washington",
    state: "DC",
    zipCode: "20220"
  },
  telephone: "208-346-0715",
  creditCard: {
    network: "Visa",
    number: "4556781272473393"
  }
}

  2. Define an alias that references multiple fields to get the value of the projected field:

    Customer.byName("Alice", "Appleseed").first() {
  myCity: .address.city,
  fullName: .firstName + " " + .lastName
}
    {
  myCity: "Washington",
  fullName: "Alice Appleseed"
}

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!