Phantom References

What are phantoms?

A phantom in Faros is an entity that does not exist in the Faros graph but is referenced by another object. Essentially, if an entity in Faros has a foreign key reference but there is no object matching the given key, we call this missing object a phantom.

For example, let’s say I have a task in my Faros data that has an attached PR in Jira. In my Faros data this task will have an associated PR reference. If this specific PR has not been pulled into Faros yet, that PR reference will be pointing to a PR that does not exist in the Faros graph. In this situation we would say that the task has a phantom PR.

Why do they exist in Faros?

In the example above, the phantom reference exists because Faros does not have an entry for the specific PR the task is referencing. This is most likely because Faros hasn’t started pulling pull request data yet. Once that data is populated the Task will refer to a PR that now exists so the reference will no longer be a phantom reference.

We created support for phantoms for this exact use case. When pulling the task data we want to capture all the data we can, even if that data includes references to things that don’t exist in the Faros graph yet. Once those missing pieces get pulled in everything connects up without any additional work needed.

When can phantoms be a problem?

Phantoms are great when they are referencing data that will be added to the graph in the future. But they are not so great when they refer to objects that no longer exist or will never exist.

Dangling phantoms are phantoms that reference an object that existed at one point but has since been deleted. Most sources and UI interactions clean up these all references to an object when it is deleted, but there are some edge cases where a dangling phantom remains.

Incorrect phantoms are phantoms that refer to an object key that will never exist. These typically happen from data that is manually entered or incorrectly instrumented events. If your keys and references don’t match up when you’re creating Faros data you can get into situations where two objects that should be connected are referencing the wrong key.

Both dangling phantoms and incorrect phantoms should be deleted.

How do I clean them up?

Reach out to Customer Success at Faros to quickly clean up your data.