Mitglieder-MatchCompatible with Milvus v3.0.2+
Übersicht
Der Membership-Match-Filter filtert Entitäten, indem er prüft, ob der Wert eines Skalarfelds zu einer vom Aufrufer bereitgestellten Menge gehört. Der Client erstellt einen kompakten binären Membership-Filter-Blob und übergibt diesen als Wert für eine Ausdrucksvorlage.
Dies ersetzt umfangreiche „ IN [...] “-Listen. Ein „ IN “-Filter serialisiert jedes Element in die Anfrage, sodass ausreichend große Elementmengen das gRPC-Empfangslimit des Proxys überschreiten können. Mit „ membership_match “ validiert der Proxy den Blob und bindet ihn in den Abfrageplan ein, ohne eine Elementliste neu zu erstellen.
Ablauf des „Membership Match“-Workflows: Der Client erstellt einen wiederverwendbaren Blob, der Proxy validiert ihn und die QueryNodes werten ihn aus.
Das Diagramm zeigt die festgelegte Arbeitsteilung. Der Client erstellt den Blob einmalig und verwendet ihn für mehrere Anfragen wieder; der Proxy überprüft die Ummantelung und die Größenbeschränkungen und bettet den Blob unverändert in den Abfrageplan ein; und die QueryNodes werten den Plan anhand von Rohdaten oder eines Indexes aus.
Der Operator verfügt über zwei Kodierungen mit unterschiedlichen Korrektheitsgarantien:
- Bloom (
type=bloom): Ungefähre Zugehörigkeit. Falsch-positive Ergebnisse sind möglich; bei einem gültigen Filter sind keine falsch-negativen Ergebnisse zu erwarten. Typische Anwendung: Filter mit hohem Datenaufkommen zur Zielgruppenansprache oder zum Ausschluss, bei denen gelegentliche falsch-positive Ergebnisse akzeptabel sind. - Roaring (
type=roaring): Exakte Zugehörigkeit für ganzzahlige Werte. Typische Verwendung: ACLs, Mandantensichtbarkeit, Compliance-Filter und Löschvorgänge nach ID-Sätzen.
Verwenden Sie die Bloom- Zugehörigkeit nicht für Autorisierungsentscheidungen oder destruktive Löschvorgänge. Ein falsch-positiver Treffer kann eine Entität offenlegen oder eine Entität löschen, die nicht zur beabsichtigten Menge gehört.
Checkliste für den Betrieb
- Überprüfen Sie den Typ des Zielfelds und erstellen Sie den Blob aus derselben Wertedomäne.
- Wählen Sie „Bloom“ nur dann aus, wenn Fehlalarme akzeptabel sind.
- Wählen Sie „Roaring“ für ACL-, Compliance-, Mandantenisolierungs- und Löschvorgänge.
- Erstellen Sie große Blobs einmalig und verwenden Sie sie wieder; erstellen Sie sie nicht bei jeder Anfrage neu.
- Planen Sie die Blob-Größe in serialisierten Bytes ein, nicht anhand der Anzahl der Elemente.
- Schließen Sie in einem Cluster mit gemischten Versionen zunächst das rollierende Upgrade ab (zuerst die Proxys), bevor Sie „
membership_match“ aktivieren. - Testen Sie den Ausdruck an einer Nicht-Produktionssammlung, bevor Sie einen destruktiven Workflow aktivieren.
Syntax des Ausdrucks
membership_match(<field>, {<template>}, type=bloom)
membership_match(<field>, {<template>}, type=roaring)
membership_match(<field>, {<template>})
not membership_match(<field>, {<template>}, type=bloom)
Das zweite Argument ist ein Platzhalter in der Vorlage. Das SDK stellt den Platzhalterwert als Protobuf- bytes bereit, der den vom Client erstellten Filter-Blob enthält. Halten Sie den type in Produktionsausdrücken explizit, damit der beabsichtigte Korrektheitsvertrag im Code und in den Protokollen sichtbar ist.
Das Argument „ type “ ist optional. Jeder Blob enthält einen selbstbeschreibenden Magic-Header – „ MBF1 “ für Bloom und „ MRB1 “ für Roaring – und der Server liest diesen Header aus, wenn „ type “ weggelassen wird. Ein expliziter „ type “, der mit dem Blob-Header in Konflikt steht, wird als Anforderungsfehler abgelehnt, und unbekannte oder abgeschnittene Header führen zu einem „Fail-Closed“-Zustand.
Wählen Sie die Kodierung
Verwenden Sie „Bloom“, wenn ein Fehlalarm akzeptabel ist. „Bloom“ akzeptiert Felder mit vorzeichenbehafteten Ganzzahlen (INT8/16/32/64), VARCHAR-Felder und JSON-Pfade. Ein Bloom-Filter ist keine exakte Zulassungsliste.
fpr (Falsch-Positiv-Rate) ist die Wahrscheinlichkeit, dass ein Bloom-Filter einen Wert als Element meldet, obwohl dieser Wert nie eingefügt wurde: „ fpr=0.005 “ bedeutet, dass etwa einer von 200 Nicht-Element-Werten fälschlicherweise als vorhanden gemeldet wird. Eine niedrigere FPR erzeugt einen größeren Blob.
Verwenden Sie „Roaring“, wenn jede Übereinstimmung exakt sein muss. „Roaring“ akzeptiert nur vorzeichenbehaftete Ganzzahlfelder; Elemente werden vor der Serialisierung auf INT64 vorzeichenverlängert, sodass ein INT8 mit dem Wert -1 und ein INT64 mit dem Wert -1 dasselbe Element darstellen. Verwenden Sie diese Option nicht für UUIDs oder andere Zeichenfolgenfelder.
| Dimension | Bloom (type=bloom) | Roaring (type=roaring) |
|---|---|---|
| Genauigkeit | Ungefähr; falsch-positive Ergebnisse möglich; keine falsch-negativen Ergebnisse | Exakt; keine falsch-positiven und keine falsch-negativen Ergebnisse |
| Felder | INT8/16/32/64, VARCHAR, JSON-Pfade | Nur vorzeichenbehaftete INT8/16/32/64 |
| Blob-Größe | Anzahl der Elemente und FPR; etwa 11 Bit pro Element bei einem FPR von 0,005; Körper als Zweierpotenz | Wertverteilung; dichte Mengen lassen sich auf weitaus kleinere Größen komprimieren; zufällige 64-Bit-Werte erreichen die Obergrenze des High-Containers von 262.144 |
| Löschen | Wird beim Parsen abgelehnt | Zulässig |
| Typische Verwendung | Zielgruppen- und Ausschlussfilter | ACL, Compliance, Mandantenisolierung, Löschen nach ID-Satz |
JSON-Pfade sind streng typisiert, Zeile für Zeile: Eine JSON -Zeichenkette wird als VARCHAR- Wert ausgewertet, eine JSON -Ganzzahl als INT64- Wert, und ein JSON-Double entspricht niemals einem ganzzahligen Element – im Gegensatz zum exakten „ IN “, bei dem 5,0 gleich 5 ist. Wenn Ihre Schreiboperationen Ganzzahlen als Float kodieren, normalisieren Sie diese beim Schreiben oder verwenden Sie ein typisiertes Skalarfeld.
Erstellen Sie bei beiden Kodierungen die Elementmenge aus derselben Wertedomäne wie das Zielfeld. Erstellen Sie keinen Bloom-Filter aus dem String- "10086" und wenden Sie ihn nicht auf ein „ INT64 “-Feld an. Der Blob-Header protokolliert die eingefügten Wertdomänen, und ein Blob mit falscher Domäne wird vom Proxy mit einem Parameterfehler abgelehnt, anstatt stillschweigend keine Übereinstimmung zu finden. Verwenden Sie einen erstellten Blob über mehrere Anfragen hinweg wieder, anstatt ihn für jede Abfrage neu zu erstellen.
Für Mengen mit wenigen tausend Elementen oder weniger bleibt die einfache „ IN “-Methode die einfachste Option. Der Server wählt nicht zwischen „IN“, „Bloom“ und „Roaring“ aus. Die Auswahl der Kodierung liegt in der Verantwortung des Aufrufers.
So wählen Sie eine Kodierung aus:
- Stellen Sie fest, ob die Arbeitslast Fehlalarme toleriert. Ist dies nicht der Fall, kommt „Bloom“ niemals in Frage.
- Für eine exakte Zugehörigkeit verwenden Sie „Roaring“ mit einem Feld für vorzeichenbehaftete Ganzzahlen. Dichte oder gruppierte Werte lassen sich zu den kleinsten Blobs komprimieren.
- Prüfen Sie die Größenbeschränkungen. Gleichmäßig zufällige 64-Bit-Werte können die Obergrenze von 262.144 für High-Container oder die Größenbeschränkungen überschreiten. Ist dies der Fall, verwenden Sie eine herkömmliche IN -Liste, die den Anforderungsgrenzen entspricht.
- Für eine exakte Zugehörigkeit bei nicht-ganzzahligen Feldern verwenden Sie „IN“. Für diese Felder gibt es keine Kodierung für exakte Zugehörigkeit.
Die Mitgliedschaftsabgleichfunktion ist über die RESTful-HTTP-API nicht verfügbar. Parameter in HTTP-Ausdrucksvorlagen akzeptieren nur Werte vom Typ „bool“, „number“, „string“ und „array“; es gibt keinen binären Typ „ bytes “ für den Blob. Verwenden Sie ein gRPC-basiertes SDK, um Mitgliedschafts-Blobs zu übergeben.
SDK-Anfragemuster
Die folgenden Codeausschnitte konzentrieren sich auf die Erstellung von Mitgliedschafts-Blobs und deren Übergabe als Filtervorlagenparameter. Sie setzen voraus, dass die Sammlungen und Felder bereits vorhanden und geladen sind, die SDK-Clients verbunden sind und Abfragevektoren, Mitgliederlisten sowie andere referenzierte Variablen definiert sind. Die Einrichtung der Sammlungen und das vollständige Anwendungsgerüst werden ausgelassen.
from pymilvus import MilvusClient, build_bloom_filter, build_roaring_bitmap
client = MilvusClient(uri="http://localhost:19530")
bloom_blob = build_bloom_filter(["creator-a", "creator-b"], fpr=0.005)
client.search(collection_name="posts", data=[query_vector], anns_field="embedding", limit=10,
filter="membership_match(creator_id, {members}, type=bloom)",
filter_params={"members": bloom_blob})
roaring_blob = build_roaring_bitmap([1001, 1002, 1003])
client.query(collection_name="docs", filter="membership_match(user_id, {members}, type=roaring)",
filter_params={"members": roaring_blob}, output_fields=["user_id", "title"])
bloomBlob, err := milvusclient.NewBloomFilterBlob([]int64{1001, 1002}, fpr)
if err != nil { return err }
search := milvusclient.NewSearchOption("posts", topK, vectors).
WithFilter("membership_match(creator_id, {members}, type=bloom)").
WithTemplateParam("members", bloomBlob)
roaringBlob, err := milvusclient.NewRoaringBitmapBlob([]int64{1001, 1002})
if err != nil { return err }
query := milvusclient.NewQueryOption("docs").
WithFilter("membership_match(user_id, {members}, type=roaring)").
WithTemplateParam("members", roaringBlob)
byte[] bloomBlob = BloomFilterUtils.buildBloomFilter(userIds, BloomFilterUtils.DEFAULT_FPR);
QueryReq request = QueryReq.builder().collectionName("docs")
.filter("membership_match(user_id, {members}, type=bloom)")
.filterTemplateValues(Collections.singletonMap("members", bloomBlob)).build();
byte[] roaringBlob = RoaringBitmapUtils.buildRoaringBitmap(userIds);
const bloomBlob = buildBloomFilter(userIds);
await client.query({ collection_name: 'docs',
filter: 'membership_match(user_id, {members}, type=bloom)',
exprValues: { members: bloomBlob } });
const roaringBlob = buildRoaringBitmap(integerIds);
Löschen mit „Roaring“
Verwenden Sie beim Löschen von Entitäten, die durch eine externe Ganzzahl-ID-Menge ausgewählt wurden, einen exakten Roaring-Blob. Überprüfen Sie die Mitgliedermenge und den Feldtyp der Sammlung, bevor Sie den Löschbefehl ausführen. Verwenden Sie kein Bloom: Eine ungefähre Zugehörigkeit ist kein sicheres Löschprädikat, und Bloom-Formen werden in Löschausdrücken bereits bei der Analyse abgelehnt.
roaring_blob = build_roaring_bitmap([1001, 1002, 1003])
client.delete(collection_name="docs", filter="membership_match(id, {members}, type=roaring)",
filter_params={"members": roaring_blob})
roaringBlob, err := milvusclient.NewRoaringBitmapBlob([]int64{1001, 1002, 1003})
if err != nil { return err }
_, err = client.Delete(ctx, milvusclient.NewDeleteOption("docs").
WithExpr("membership_match(id, {members}, type=roaring)").
WithTemplateParam("members", roaringBlob))
byte[] roaringBlob = RoaringBitmapUtils.buildRoaringBitmap(userIds);
DeleteReq request = DeleteReq.builder().collectionName("docs")
.filter("membership_match(id, {members}, type=roaring)")
.filterTemplateValues(Collections.singletonMap("members", roaringBlob)).build();
const roaringBlob = buildRoaringBitmap(integerIds);
await client.delete({ collection_name: 'docs',
filter: 'membership_match(id, {members}, type=roaring)',
exprValues: { members: roaringBlob } });
Die Löschsemantik folgt einer exakten, dreipoligen Übereinstimmung:
| Feldwert | membership_match(…) | nicht membership_match(…) |
|---|---|---|
| NULL | kein Abgleich (NULL) | keine Übereinstimmung (NULL) |
| in der Mitgliedermenge | Übereinstimmung | keine Übereinstimmung |
| außerhalb der Menge | keine Übereinstimmung | Übereinstimmung |
Die Tabelle lässt sich Zeile für Zeile wie folgt interpretieren: Ein „Delete“ mit „ membership_match “ entfernt die Entitäten innerhalb der Menge, ein „Delete“ mit „ not membership_match “ entfernt die Entitäten außerhalb der Menge, und NULL-Entitäten bleiben bei beiden Polaritäten erhalten.
- Entitäten mit einem NULL-Feldwert werden unter keiner der beiden Polaritäten gelöscht.
- Eine leere Bitmap löscht nichts. „
not membership_match(<field>, {<empty>}, type=roaring)“ löscht jede Entität mit einem Nicht-NULL-Feldwert – also genau das Komplement –, was je nach Design eine große Menge sein kann. not membership_matchist das exakte Komplement der Elementmenge über Nicht-NULL-Entitäten, keine Annäherung.
Bei versiegelten Segmenten, die indexbasiert geladen werden und keine rohen Skalardaten enthalten, verwendet die Auswertung eine begrenzte Rückwärtssuche, sofern der Index dies unterstützt. Wenn weder rohe Felddaten noch ein geeigneter Index verfügbar sind, schlägt die Anfrage mit „ FieldNotLoaded “ fehl, anstatt ungefilterte Entitäten zurückzugeben.
Operative Einschränkungen
| Einstellung | Standard | Konfigurierbar | Was es begrenzt |
|---|---|---|---|
proxy.maxMembershipFilterSize | 64 MiB | milvus.yaml Proxy | ein Blob-Inhalt |
proxy.maxMembershipFilterPlanSize | 128 MiB | milvus.yaml Proxy | Aggregat pro Anfrage |
proxy.grpc.serverMaxRecvSize | 128 MiB | milvus.yaml Proxy | gesamte Anfrage |
| Roaring High-Container-Obergrenze | 262.144 | im Code festgelegt | pro Filter |
| Geschätzter Speicherbedarf für „Roaring Decoded“ | 64 MiB | im Code festgelegt | pro Filter |
| MBF1-Format-Obergrenze | 128 MiB | im Code festgelegt | Obergrenze des Blob-Formats |
Bloom fpr | 0,005 | Client-Builder | Zielwert für Falsch-Positiv-Ergebnisse |
Die Einstellungen unter „ proxy.* “ sind Teil der Milvus-Serverkonfiguration: Sie werden vom Cluster-Betreiber unter milvus.yaml im Abschnitt „ proxy “ festgelegt und können zum Zeitpunkt der Filterung nicht pro Anfrage oder pro Ausdruck angepasst werden. Die „Roaring Admissions“ und die Obergrenze für das MBF1-Format sind in der Implementierung fest vorgegeben und können nirgendwo konfiguriert werden. Die Zeile „ fpr “ ist die einzige clientseitige Steuerungsmöglichkeit: Sie wird beim Erstellen des Blobs ausgewählt, wobei der zulässige Bereich zwischen 0,0001 und 0,05 liegt.
Der Blob-Körper fasst bei der Standard-FPR maximal etwa 48,6 Millionen INT64-Elemente, wobei der feste 32-Byte-Envelope-Header zusätzlich zulässig ist. Das anfrageweite Budget deckt die aggregierte serialisierte Größe der Mitgliederlisten sowie die aggregierte geschätzte dekodierte Größe der Roaring-Filter ab; HybridSearch-Unteranfragen und Scorer-Filter teilen sich dieses Budget. Bloom-Körper sind Zweierpotenzen: Eine Mitgliederanzahl, die knapp über einer Stufengrenze liegt, verdoppelt den Blob, und ein etwas höherer FPR passt oft in die nächstniedrigere Stufe. Wenn der Proxy einen übergroßen Bloom-Blob ablehnt, schlägt der Fehler eine „ fpr “ vor, die passt.
- Die Ergebnisse von Mitgliedschaftsausdrücken werden nicht über mehrere Abfragen hinweg zwischengespeichert.
- Cluster mit gemischten Versionen schlagen fehl: QueryNodes, auf denen älterer Code läuft, lehnen Pläne ab, die Knoten des Mitgliedschaftsplans enthalten. Aktualisieren Sie zuerst die Proxys und schließen Sie dann das rollierende Upgrade ab, bevor Sie den Operator aktivieren.
- Serverprotokolle schwächen Blob-Bytes ab. Der Ausdruckstext enthält nur den Vorlagennamen; die binäre Nutzlast wird außerhalb des Bandes in den Vorlagenwerten übertragen.