Working with Phantoms

Phantoms are records that are created automatically by the Faros Destination to connect records together. Since they are not explicitly specified by the data we import, they lack an origin field. By default, we exclude all records with missing origin from our queries. Said another way, we exclude phantoms by default in our query responses.

Under the hood, our queries operate modally based on an enum setting called phantoms. It has the following values:

• exclude (default): return non-phantom records
• only: return only phantoms
• include: return all records
• include-nested-only: return phantoms in nested objects (aka references) but filter them out of top-level objects.

You can set phantoms via a query parameter in the URL:

https://prod.api.faros.ai/graphs/default/graphql?phantoms=include

Alternatively, you can add GraphQL variables to your query and specify the phantoms parameter like so:

{  
  "phantoms": "include"  
}

Note: to support the variable method, we’ve made phantoms a reserved key name. It cannot be used as an actual variable name in GraphQL.