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 customer = {
  firstName: "Bob",
  lastName: "Brown",
  email: "bob.brown@example.com",
  address: {
    street: "72 Waxwing Terrace",
    city: "Washington",
    state: "DC",
    zipCode: "20002"
  },
  telephone: "719-872-8799",
  creditCard: {
    network: "Visa",
    number: "4916112310613672"
  }
}

customer {
  lastName,
  address {
    street
  }
}
{
  lastName: "Brown",
  address: {
    street: "72 Waxwing Terrace"
  }
}

Array projection

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

let stores = [
  {
    name: "DC Fruits",
    address: {
      street: "13 Pierstorff Drive",
      city: "Washington",
      state: "DC",
      zipCode: "20220"
    }
  },
  {
    name: "Party Supplies",
    address: {
      street: "7529 Capitalsaurus Court",
      city: "Washington",
      state: "DC",
      zipCode: "20002"
    }
  },
  {
    name: "Foggy Bottom Market",
    address: {
      street: "4 Florida Ave",
      city: "Washington",
      state: "DC",
      zipCode: "20037"
    }
  }
]

stores {
  name
}
[
  {
    name: "DC Fruits"
  },
  {
    name: "Party Supplies"
  },
  {
    name: "Foggy Bottom Market"
  }
]

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.

For example, the following query updates a Store collection document to add a stock field. The stock field contains a reference to a Product collection document.

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")
}

When the stock field is projected, the referenced is resolved and the full Product collection document is returned:

Store.byName("Party Supplies").first() {name,  stock}
{
  name: "Party Supplies",
  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:

    Customer.byEmail("alice.appleseed@example.com").first()
    {
  id: "401666284571328585",
  coll: Customer,
  ts: Time("2099-06-25T12:14:29.440Z"),
  firstName: "Alice",
  lastName: "Appleseed",
  email: "alice.appleseed@example.com",
  address: {
    street: "87856 Mendota Court",
    city: "Washington",
    state: "DC",
    zipCode: "20220"
  },
  telephone: "208-346-0715",
  creditCard: {
    network: "Visa",
    number: "4556781272473393"
  }
}

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

    Customer.byEmail("alice.appleseed@example.com").first() {
  myCity: .address.city
}
    {
  myCity: "Washington"
}

 

Example projecting multiple fields:

  1. Given the following document:

    Customer.byEmail("alice.appleseed@example.com").first()
    {
  id: "401666284571328585",
  coll: Customer,
  ts: Time("2099-06-25T12:14:29.440Z"),
  firstName: "Alice",
  lastName: "Appleseed",
  email: "alice.appleseed@example.com",
  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.byEmail("alice.appleseed@example.com").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!