Documenting/Inspecting the internal data behind Collection/Ref/etc documents?

[lewisl]

Hi! I have a multi-collection index set up as described here: Multi-collection indexes :: Fauna Documentation, and wanted to query which collection each document returned from the index was from in order to branch on it, which required extracting that information from the ref for each document.

Through a bunch of trial and error, I eventually figured out that Ref and Collection both seem to be documents backed by internal data structures that can be accessed through Select, so getting the collection name from a ref could look something like this:

> Select(["collection", "id"], Ref(Collection('apps'), "some-id"))
"apps"

That’s enough for my current use case, but I was wondering if it’s possible to inspect the data behind these opaque documents like Collection/Ref, or if they’re documented somewhere, so I don’t have to do as much trial and error next time I have a similar use case. Thanks!

[ptpaterson]

References are their own special data type. References are not Documents and cannot have user defined data attached to them.

Types

Every Ref has id and collection fields. Note that references to schema are also Refs, so you can also Select the id and collection for Schema Refs as well.

Here is an example:

Map(
  [
    Ref(Collection("users"), "319254125213646912"), // Document Ref
    Collection("users"),                            // user Schema Ref
    Collections()                                   // native Schema Ref
    Function("Test"),                               // user Schema Ref
    Functions()                                     // native Schema Ref
  ],
  ref => ({
    id: Select("id", ref),
    collection: Select("collection", ref, null)
  })
)

Here is the result as formatted FQL

[
  { id: "319254125213646912", collection: Collection("users") },
  { id: "users", collection: Collections() },
  { id: "collections", collection: Collections() },
  { id: "users", collection: Collections() },
  { id: "collections", collection: Collections() },
  { id: "Test", collection: Functions() },
  { id: "collections", collection: Collections() },
]

Here’s the raw output for comparison. I like to share this, because it shows the recursive nature of the Refs.

Note that the over-the-wire protocol is an implementation detail and subject to change. The drivers abstract this away, for example providing getters for id and collection on Refs. Do NOT rely on manipulating the raw output for production purposes.

[
  {
    "@ref": {
      "id": "319254125213646912",
      "collection": {
        "@ref": {
          "id": "users",
          "collection": {
            "@ref": {
              "id": "collections"
            }
          }
        }
      }
    }
  },
  {
    "@ref": {
      "id": "users",
      "collection": {
        "@ref": {
          "id": "collections"
        }
      }
    }
  },
  {
    "@ref": {
      "id": "collections",
      "collection": {
        "@ref": {
          "id": "collections"
        }
      }
    }
  },
  {
    "@ref": {
      "id": "tester",
      "collection": {
        "@ref": {
          "id": "functions"
        }
      }
    }
  },
  {
    "@ref": {
      "id": "functions",
      "collection": {
        "@ref": {
          "id": "collections"
        }
      }
    }
  }
]