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:

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

Document relationship dereferencing

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

Store.firstWhere(.name == "Party Supplies")!.update({
  stock: Product.firstWhere(.name == "pinata")
})
{
  id: "386968888559009860",
  coll: Store,
  ts: Time("2024-01-15T06:53:44.490Z"),
  name: "Party Supplies",
  address: {
    street: "7529 Capitalsaurus Court",
    city: "Washington",
    state: "DC",
    zipCode: "20002"
  },
  stock: Product.byId("386968888563204164")
}

 

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.firstWhere(.name == "Party Supplies") { stock }
{
  stock: {
    id: "386968888563204164",
    coll: Product,
    ts: Time("2024-01-15T06:45:40.390Z"),
    name: "pinata",
    description: "Original Classic Donkey Pinata",
    price: 24.99,
    quantity: 40,
    store: Store.byId("386968888559009860"),
    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:

    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!