Projection and field aliasing

Projection allows you to select the fields to be returned.

Projection is supported for Struct, Array, Set, and Document types.

Any expression can be projected, including single values.

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

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.

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

For a set, the projection is applied to each element of the every returned element has the requested shape:

Books.all() { title }
{
  data: [
    {
      title: "This Side of Paradise"
    },
    {
      title: "Tender Is the Night"
    },
    {
      title: "A Passage to India"
    },
    {
      title: "The Sun Also Rises"
    },
    {
      title: "The Doors of Perception"
    }
  ]
}

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.

Given this document set:

Imagist.all()
{
  "data": [
    {
      "id": "357667632564928545",
      "coll": "Imagist",
      "ts": "2023-02-25T20:34:45.020Z",
      "fullName": {
        "firstName": "Jack",
        "lastName": "London"
      },
      "pubdate": "1903"
    },
    {
      "id": "357667663307079713",
      "coll": "Imagist",
      "ts": "2023-02-25T20:35:14.330Z",
      "fullName": {
        "firstName": "Joe",
        "lastName": "Conrad"
      },
      "pubdate": "1902"
    }
  ]
}

This projection selects fields across multiple documents:

Imagist.all() {
  pubdate
}
{
  "data": [
    {
      "pubdate": "1903"
    },
    {
      "pubdate": "1902"
    }
  ]
}

This request narrows the selection to fields in a single document:

Imagist.all().where(.pubdate == "1902") {
  fullName
}
{
  "data": [
    {
      "fullName": {
        "firstName": "Joe",
        "lastName": "Conrad"
      }
    }
  ]
}

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:

    Person.byId("360010095407398946")
    {
  "id": "360010095407398946",
  "coll": "Person",
  "ts": "2023-05-24T20:05:44.430Z",
  "name": "Janine Labrune",
  "address": {
    "street": "67, rue des Cinquante Otages",
    "city": "Nantes",
    "country": "France",
    "zip": 44000
  }
}

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

    Person.byId("360010095407398946"){
  myCity: .address.city 
}
    {
  "myCity": "Nantes"
}

 

Example projecting multiple fields:

  1. Given the following document:

    Person.byId("365709377885175842")
    {
  "id": "365709377885175842",
  "coll": "Person",
  "ts": "2023-05-25T14:54:51Z",
  "firstName": "Janine",
  "lastName": "Labrune",
  "address": {
    "street": "67, rue des Cinquante Otages",
    "city": "Nantes",
    "country": "France",
    "zip": 44000
  }
}

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

    Person.byId("365709377885175842") {
  myCity: .address.city,
  fullName: .firstName + " " + .lastName
}
    {
  "myCity": "Nantes",
  "fullName": "Janine Labrune"
}

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!