HHostingByteSoftware
Ctrl K
ComunidadGuías…

specs/global-vertex-property-index.md

Rama master · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# Global Vertex Property Index

**Status:** Draft
**Author:** Colin Barry
**Last updated:** 2026-07-07

> Allow a property index to be created on vertices without specifying a label,
> so that queries filtering on a property across all labels can use an index
> lookup instead of a full scan.

---

## 1. Motivation

Memgraph's existing vertex property indices require a label:
`CREATE INDEX ON :Label(prop)`. This means a query like
`MATCH (n) WHERE n.ID = '01J...'` cannot use an index unless the caller also
specifies a label. In practice, many workloads (particularly agentic/LLM-driven
retrieval) produce property-based lookups without knowing or caring about the
node's label.

Today the only workarounds are:
- to duplicate the index on every label that carries the property, and to
always include a label in the query. This is fragile and often impossible when
the query is generated by an external system.
- to add a dummy label specifically for indexing.

Memgraph already supports **global edge property indices** (edge indices without
an edge type). This feature adds the vertex equivalent.

---

## 2. Core principle

> **A global vertex property index is a label-agnostic property index. It indexes
> every vertex that has the property, regardless of labels.**

It is not a replacement for label+property indices. When both exist, the planner
should always prefer the label+property index: a label+property index is a
subset of the global index (it contains only vertices with that label), so it is
always at least as selective, never less.

---

## 3. User-facing surface

### Creating and dropping

```cypher
CREATE GLOBAL INDEX ON :(prop);
DROP GLOBAL INDEX ON :(prop);
```

This mirrors the existing global edge property index syntax
(`CREATE GLOBAL EDGE INDEX ON :(prop)`), without the `EDGE` keyword.

- `prop` is required.
- Creating an index that already exists returns an informational notice (not an
  error), consistent with existing index behavior.
- Dropping an index that does not exist returns an informational notice.

### Visibility

Global vertex property indices appear in the output of `SHOW INDEX INFO` with
index type `"vertex-property"` and an empty label column, following the pattern
of the global edge property index (type `"edge-property"`).

They are also included in `SHOW STORAGE INFO` index counts and in `dump`
output (so that a logical dump can recreate them).

A new `ApproximateVertexCount(PropertyId)` overload (without a label) is
exposed through the storage and db accessor APIs, used by both
`SHOW INDEX INFO` (count column) and the planner cost estimator.

### C API (query modules)

The `mgp_*` procedure API exposes index management functions. The following
new functions are needed:

- `mgp_create_global_property_index(graph, property, result)`
- `mgp_drop_global_property_index(graph, property, result)`

`mgp_graph_show_index_info` must include global vertex property indices in its
output.

Note: the existing global edge property index does not have corresponding
`mgp_*` C API functions. Those should be added separately as a follow-up.

### Availability

Community and enterprise. No license gate, same as label+property indices.
In-memory storage mode only — disk storage is not supported (consistent with
the global edge property index).

---

## 4. Query patterns and planner behavior

The global vertex property index enables index-backed execution for vertex
scans that filter on a property without specifying a label.

### Direct use (no label in query)

| Query pattern | Planner operator |
|---|---|
| `MATCH (n) WHERE n.prop = val` | `ScanAllByPropertyValue` |
| `MATCH (n) WHERE n.prop > val` (or any range) | `ScanAllByPropertyRange` |
| `MATCH (n) WHERE n.prop IS NOT NULL` | `ScanAllByProperty` |
| `MATCH (n) WHERE n.prop IN [...]` | Unrolled `ScanAllByPropertyValue` |

### Fallback use (label in query, no label+property index)

When a query specifies a label but no label+property index exists for that
combination, the planner may use the global vertex property index and apply a
post-scan label filter — the same pattern the edge planner already uses for
global edge property indices. This is still significantly cheaper than a full
vertex scan.

When both a label+property index and a global property index exist, the planner
**always prefers the label+property index** (it is more selective).

### Cost model

The global vertex property index is expected to be less selective than a
label+property index (it contains entries across all labels). The cost estimator
should reflect this so the planner makes the right choice when both are
available.

### Metrics

Each new operator has a corresponding per-database metric counter, following
the existing pattern (e.g. `scan_all_by_edge_property_operator` for the edge
equivalent):

- `scan_all_by_property_operator`
- `scan_all_by_property_value_operator`
- `scan_all_by_property_range_operator`

These are exposed via the OpenMetrics (Prometheus) endpoint only, consistent
with existing operator counters.

---

## 5. Design decisions

### D1 — Single-property indices only (for now)

Global vertex property indices support exactly one property. Composite
(multi-property) and nested (property-of-property) global indices are deferred.

*Rationale.* The driving use case is a single-property lookup (`n.ID`).
Memgraph already has composite label+property indices, and extending the global
index to composite is a natural follow-up — but it multiplies the storage,
planner, and grammar surface area. Shipping single-property first lets us
validate the feature end-to-end with the customer before committing to the
larger scope.

---

## 6. Storage and data structure

The global vertex property index stores `(property_value, vertex)` pairs for
every vertex that has the indexed property, across all labels. The
implementation should mirror the existing label+property index structure (a
skip-list keyed by `(value, vertex)`), consistent with how the global edge
property index mirrors the edge-type+property index.

### Maintenance

- The index is updated on every vertex **create**, **property set**, and
  **property remove**, regardless of label.
- Label changes (adding/removing a label) do **not** affect the global vertex
  property index, since it is label-agnostic.
- The index participates in MVCC visibility the same way label+property indices
  do.
- Garbage collection of obsolete index entries follows the same mechanism as
  label+property indices.
- The `IndicesInfo` struct gains a new `vertex_property` field
  (`std::vector<PropertyId>`), mirroring the existing `edge_property` field.

---

## 7. Durability

### Snapshot and WAL

Global vertex property indices are persisted in snapshots and WAL, using the
existing index-storage infrastructure. Creating or dropping a global vertex
property index is a WAL-logged storage global operation, requiring new
`StorageGlobalOperation` entries (`GLOBAL_VERTEX_PROPERTY_INDEX_CREATE` and
`GLOBAL_VERTEX_PROPERTY_INDEX_DROP`), with corresponding WAL delta types and
replication handler cases — the same plumbing as the global edge property
index.

### Version bump

The snapshot/WAL format version must be bumped. Older versions of Memgraph
cannot read a snapshot or WAL that contains global vertex property index
entries. This is a one-way migration; downgrade is not supported once the
index is created.

### Recovery

On recovery from snapshot or WAL replay, global vertex property indices are
rebuilt the same way label+property indices are.

---

## 8. Replication

Creating or dropping a global vertex property index is replicated as standard
DDL, consistent with label+property indices. The new `StorageGlobalOperation`
delta types (§7) are handled by the replication handlers in the same way as
their global edge property index counterparts.

---

## 9. Dump and restore

`SHOW INDEX INFO` and the `dump` query module include global vertex property
indices, so a logical dump produces the correct `CREATE GLOBAL INDEX` statements
and a restore recreates them.

---

## 10. Multi-tenancy

Global vertex property indices are per-database, following the same rules as
all other index types. No special multi-tenancy handling is required.

---

## 11. Guarantees and non-goals

**Guarantees**

- A global vertex property index indexes every vertex with the property,
  regardless of labels.
- The planner uses the index for label-less property lookups and as a fallback
  for label+property lookups when no specific index exists.
- The index is durable, replicated, and included in dump output.

**Non-goals (out of scope for this release)**

- **Global vertex property uniqueness constraints** — only the index, not a
  constraint.
- **Composite global indices** (multiple properties) — not in this release.
- **Text, vector, or point global vertex indices** — only the standard property
  index.
- **Disk storage** — in-memory only, consistent with the global edge property
  index.

---

## 12. Known limitations and future direction

- **Composite / multi-property global indices** may be added in a future
  release if there is demand. (See D1)
- **C API for global edge property index** — the existing global edge property
  index lacks `mgp_*` C API functions; these should be added alongside the
  vertex equivalents.