memgraph/docs/dev/storage/indexes.md

# Label indexes

These are unsorted indexes that contain all the vertices that have the label
the indexes are for (one index per label). These kinds of indexes get
automatically generated for each label used in the database.

### Updating the indexes

Whenever something gets added to the record we update the index (add that
record to index). We keep an index which might contain garbage (not relevant
records, because the value got removed or something similar) but we will
filter it out when querying the index. We do it like this because we don't
have to do bookkeeping and deciding if we update the index on the end of the
transaction (commit/abort phase), moreover current interpreter advances the
command in transaction and as such assumes that the indexes now contain
objects added in the previous command inside this transaction, so we need to
update over the whole scope of transaction (whenever something is added to the
record).

### Index Entries Label

These kinds of indexes are internally keeping track of pair (record, vlist).
Why do we need to keep track of exactly those two things?

Problems with two different approaches

1) Keep track of just the record:

  - We need the `VersionList` for creating an accessor (this in itself is a
    deal-breaker).
  - Semantically it makes sense. An edge/vertex maps bijectionally to a
    `VersionList`.
  - We might try to access some members of record while the record is being
    modified from another thread.
  - A vertex/edge could get updated, thus expiring the record in the index.
    The newly created record should be present in the index, but it's not.
    Without the `VersionList` we can't reach the newly created record.
  - Probably there are even more reasons... It should be obvious by now that
    we need the `VersionList` in the index.

2) Keep track of just the version list:

  - Removing from an index is a problem for two major reasons. First, if we
    only have the `VersionList`, checking if it should be removed implies
    checking all the reachable records, which is not thread-safe. Second,
    there are issues with concurrent removal and insertion. The cleanup thread
    could determine the vertex/edge should be removed from the index and
    remove it, while in between those ops another thread attempts to insert
    the `VersionList` into the index. The insertion does nothing because the
    `VersionList` is already in, but it gets removed immediately after.

Because of inability to keep track of just the record, or value, we need to
keep track of both of them.  Resolution of problems mentioned above, in the
same order, with (record, vlist) pair

  - simple `vlist.find(current transaction)` will get us the newest visible
    record
  - we'll never try to access some record if it's still being written since we
    will always operate on vlist.find returned record
  - newest record will contain that label
  - since we have (record, vlist) pair as the key in the index when we update
    and delete in the same time we will never delete the same record, vlist
    pair we are adding because the record, vlist pair we are deleting is
    already superseded by a newer record and as such won't be inserted while
    it's being deleted

### Querying the index

We run through the index for the given label and do `vlist.find` operation for
the current transaction, and check if the newest return record has that
label. If it has it then we return it. By now you are probably wondering
aren't we sometimes returning duplicate vlist entries? And you are wondering
correctly, we would be returning them, but we are making sure that the entires
in the index are sorted by their `vlist*` and as such we can filter consecutive
duplicate `vlist*` to only return one of those while still being able to create
an iterator to index.

### Cleaning the index

Cleaning the index is not as straightforward as it seems as a lot of garbage
can accumulate, but it's hard to know when exactly can we delete some (record,
vlist) pair. First, let's assume that we are doing the cleaning process at
some `transaction_id`, `id` such that there doesn't exist an active transaction
with an id lower than `id`.

We scan through the whole index and for each (record, vlist) pair we first
check if it was deleted before the id (i.e. no transaction with an id >= `id`
will ever again see that record), if it was deleted before we might naively
say that it's safe to delete it, but, we must take into account that when some
new record is created from this record (update operation), that record still
contains the label but by deleting this record we won't be able to see that
vlist because that new record won't add again to index because we didn't
explicitly add that label again to it.

Because of this we have to 'update' this index (record, vlist) pair. We have
to update the record to now point to a newer record in vlist, the one that is
not deleted yet. We can do that by querying the `version_list` for the last
record inside (oldest it has — remember that `mvcc_gc` will re-link not
visible records so the last record will be visible for the current GC id).
When updating the record inside the index, it's not okay to just update the
pointer and leave the index as it is, because with updating the `record*` we
might change the relative order of entries inside the index. We first have to
re-insert it with new `record*`, and then delete the old entry. And we need to
do insertion before the remove operation! Otherwise it could happen that the
vlist with a newer record with that label won't exist while some transaction
is querying the index.

Records which we added as a consequence of deleting older records will be
eventually removed from the index if they don't contain label because if we
see that the record is not deleted we try to check if that record still
contains the label. We also need to be careful here because we can't check
that while the record is being potentially updated by some transaction (race
condition), so we need can check if records still contain label if it's
creation id is smaller than our `id`, as that implies that the creating
transaction either aborted or committed as our `id` is equal to the oldest
active transaction in time of starting the GC.