Share via

Berechnete Eigenschaften in Azure Cosmos DB for NoSQL (Vorschau)

  • Artikel

GILT FÜR: NoSQL

Berechnete Eigenschaften in Azure Cosmos DB weisen Werte auf, die von vorhandenen Elementeigenschaften abgeleitet sind, wobei die Eigenschaften in den Elementen selbst jedoch nicht persistent sind. Berechnete Eigenschaften sind auf ein einzelnes Element begrenzt, und es kann in Abfragen auf gleiche Weise wie auf persistente Eigenschaften verwiesen werden. Mithilfe berechneter Eigenschaften kann eine komplexe Abfragelogik einmal geschrieben und mehrmals darauf verwiesen werden. Sie können diesen Eigenschaften einen einzelnen Index hinzufügen oder sie als Teil eines zusammengesetzten Indexes verwenden, um die Leistung zu erhöhen.

Hinweis

Haben Sie Feedback zu berechneten Eigenschaften? Teilen Sie uns Ihre Meinung mit! Sie können Feedback direkt an das Azure Cosmos DB-Entwicklungsteam senden: cosmoscomputedprops@microsoft.com.

Was ist eine berechnete Eigenschaft?

Berechnete Eigenschaften müssen sich auf der obersten Ebene im Element befinden und dürfen keinen geschachtelten Pfad aufweisen. Jede Definition einer berechneten Eigenschaft weist zwei Komponenten auf: einen Namen und eine Abfrage. Der Name ist der Name der berechneten Eigenschaft, und die Abfrage definiert die Logik zum Berechnen des Eigenschaftswerts für jedes Element. Berechnete Eigenschaften sind auf ein einzelnes Element begrenzt und können daher keine Werte aus mehreren Elementen oder andere berechnete Eigenschaften verwenden. Jeder Container kann maximal 20 berechnete Eigenschaften aufweisen.

Beispieldefinition einer berechneten Eigenschaft:

{
  "computedProperties": [
    {
      "name": "cp_lowerName",
      "query": "SELECT VALUE LOWER(c.name) FROM c"
    }
  ]
}

Einschränkungen für Namen

Es wird dringend empfohlen, berechnete Eigenschaften zu benennen, damit keine Kollision mit einem persistenten Eigenschaftennamen auftritt. Um überlappende Eigenschaftsnamen zu vermeiden, können Sie allen Namen für berechnete Eigenschaften ein Präfix oder Suffix hinzufügen. In diesem Artikel wird das Präfix cp_ in allen Namensdefinitionen verwendet.

Wichtig

Das Definieren einer berechneten Eigenschaft mithilfe desselben Namens wie eine persistente Eigenschaft führt nicht zu einem Fehler, kann jedoch ein unerwartetes Verhalten bewirken. Unabhängig davon, ob die berechnete Eigenschaft indiziert ist, werden Werte aus persistenten Eigenschaften, die denselben Namen wie eine berechnete Eigenschaft aufweisen, nicht in den Index einbezogen. Abfragen verwenden immer die berechnete Eigenschaft anstelle der persistenten Eigenschaft. Die einzige Ausnahme ist die persistente Eigenschaft, die anstelle der berechneten Eigenschaft zurückgegeben wird, wenn in der SELECT-Klausel eine Platzhalterprojektion enthalten ist. Die Platzhalterprojektion beinhaltet nicht automatisch berechnete Eigenschaften.

Folgende Einschränkungen gelten für die Namen berechneter Eigenschaften:

  • Alle berechneten Eigenschaften müssen eindeutige Namen aufweisen.
  • Der Wert der name-Eigenschaft stellt den Eigenschaftsnamen der obersten Ebene dar, mit dem auf die berechnete Eigenschaft verwiesen werden kann.
  • Reservierte Systemeigenschaftennamen wie beispielsweise id, _rid, _ts können nicht als Namen für berechnete Eigenschaften verwendet werden.
  • Der Name einer berechneten Eigenschaft darf nicht mit einem Eigenschaftenpfad übereinstimmen, der bereits indiziert ist. Diese Einschränkung gilt für alle angegebenen Indizierungspfade, einschließlich:
    • Eingeschlossene Pfade
    • Ausgeschlossene Pfade
    • Räumlichkeitsindizes
    • Zusammengesetzte Indizes

Einschränkungen für Abfragen

Abfragen in der Definition der berechneten Eigenschaft müssen syntaktisch und semantisch gültig sein, da andernfalls beim Vorgang zur Erstellung oder Aktualisierung ein Fehler auftritt. Abfragen sollten für alle Elemente in einem Container einen deterministischen Wert ergeben. Abfragen können für einige Elemente als nicht definiert oder NULL ausgewertet werden, und berechnete Eigenschaften mit nicht definierten oder NULL-Werten verhalten sich genauso wie persistente Eigenschaften mit nicht definierten oder NULL-Werten, wenn sie in Abfragen verwendet werden.

Folgende Einschränkungen gelten für Abfragedefinitionen berechneter Eigenschaften:

  • Abfragen müssen eine FROM-Klausel angeben, die den Stammelementverweis darstellt. Beispiele für unterstützte FROM-Klauseln sind FROM c, FROM root c und FROM MyContainer c.
  • Abfragen müssen eine VALUE-Klausel in der Projektion verwenden.
  • Abfragen können kein JOIN enthalten.
  • Abfragen können keine nichtdeterministischen Skalarausdrücke verwenden. Beispiele für nicht deterministische skalare Ausdrücke sind: GetCurrentDateTime, GetCurrentTimeStamp, GetCurrentTicks und RAND.
  • Abfragen können keine der folgenden Klauseln verwenden: WHERE, GROUP BY, ORDER BY, TOP, DISTINCT, OFFSET LIMIT, EXISTS, ALL, LAST, FIRST und NONE.
  • Abfragen können keine skalare Unterabfrage enthalten.
  • Aggregatfunktionen, räumliche Funktionen, nichtdeterministische Funktionen und benutzerdefinierte Funktionen werden nicht unterstützt.

Erstellen von berechneten Eigenschaften

Während der Vorschauphase müssen berechnete Eigenschaften mit dem .NET v3 oder Java v4 SDK erstellt werden. Nachdem die berechneten Eigenschaften erstellt wurden, können Sie Abfragen ausführen, die mit einer beliebigen Methode auf die Eigenschaften verweisen, einschließlich aller SDKs und Azure Data Explorer im Azure-Portal.

Unterstützte Version Hinweise
.NET SDK v3 >= 3.34.0-preview Berechnete Eigenschaften sind derzeit nur in Vorschaupaketversionen verfügbar.
Java SDK V4 >= 4.46.0 Berechnete Eigenschaften befinden sich derzeit in der Vorschauversion.
Python SDK >= v4.5.2b5 Berechnete Eigenschaften befinden sich derzeit in der Vorschauversion.

Erstellen von berechneten Eigenschaften mithilfe des SDK

Sie können entweder einen neuen Container mit definierten berechneten Eigenschaften erstellen oder Sie können berechnete Eigenschaften zu einem vorhandenen Container hinzufügen.

Hier sehen Sie ein Beispiel für das Erstellen von berechneten Eigenschaften in einem neuen Container:

ContainerProperties containerProperties = new ContainerProperties("myContainer", "/pk")
{
    ComputedProperties = new Collection<ComputedProperty>
    {
        new ComputedProperty
        {
            Name = "cp_lowerName",
            Query = "SELECT VALUE LOWER(c.name) FROM c"
        }
    }
};

Container container = await client.GetDatabase("myDatabase").CreateContainerAsync(containerProperties);

Hier sehen Sie ein Beispiel für das Aktualisieren von berechneten Eigenschaften für einen vorhandenen Container:

var container = client.GetDatabase("myDatabase").GetContainer("myContainer");

// Read the current container properties
var containerProperties = await container.ReadContainerAsync();
// Make the necessary updates to the container properties
containerProperties.Resource.ComputedProperties = new Collection<ComputedProperty>
    {
        new ComputedProperty
        {
            Name = "cp_lowerName",
            Query = "SELECT VALUE LOWER(c.name) FROM c"
        },
        new ComputedProperty
        {
            Name = "cp_upperName",
            Query = "SELECT VALUE UPPER(c.name) FROM c"
        }
    };
// Update the container with changes
await container.ReplaceContainerAsync(containerProperties);

Tipp

Bei jeder Aktualisierung von Containereigenschaften werden die alten Werte überschrieben. Wenn Sie bereits über berechnete Eigenschaften verfügen und neue hinzufügen möchten, stellen Sie sicher, dass Sie der Sammlung sowohl neue als auch vorhandene berechnete Eigenschaften hinzufügen.

Verwenden von berechneten Eigenschaften in Abfragen

Auf berechnete Eigenschaften kann in Abfragen auf dieselbe Weise wie auf persistente Eigenschaften verwiesen werden. Werte für berechnete Eigenschaften, die nicht indiziert sind, werden während der Laufzeit mithilfe der Definition der berechneten Eigenschaft ausgewertet. Wenn eine berechnete Eigenschaft indiziert ist, wird der Index auf dieselbe Weise wie für persistente Eigenschaften verwendet, und die berechnete Eigenschaft wird nach Bedarf ausgewertet. Wir empfehlen, Indizes für die berechneten Eigenschaften hinzuzufügen, um optimale Kosten und Leistung zu erzielen.

In den folgenden Beispielen wird das Schnellstartproduktdataset verwendet, das in Data Explorer im Azure-Portal verfügbar ist. Um loszulegen, starten Sie den Schnellstart, und laden Sie das Dataset in einen neuen Container.

Screenshot der zeigt, wie mit dem Schnellstart zum Laden eines exemplarischen Datensets in das Microsoft Azure-Portal begonnen wird.

Hier ist ein Beispiel für ein Element:

{
  "id": "08225A9E-F2B3-4FA3-AB08-8C70ADD6C3C2",
  "categoryId": "75BF1ACB-168D-469C-9AA3-1FD26BB4EA4C",
  "categoryName": "Bikes, Touring Bikes",
  "sku": "BK-T79U-50",
  "name": "Touring-1000 Blue, 50",
  "description": "The product called \"Touring-1000 Blue, 50\"",
  "price": 2384.07,
  "tags": [
    {
      "id": "27B7F8D5-1009-45B8-88F5-41008A0F0393",
      "name": "Tag-61"
    }
  ],
  "_rid": "n7AmAPTJ480GAAAAAAAAAA==",
  "_self": "dbs/n7AmAA==/colls/n7AmAPTJ480=/docs/n7AmAPTJ480GAAAAAAAAAA==/",
  "_etag": "\"01002683-0000-0800-0000-6451fb4b0000\"",
  "_attachments": "attachments/",
  "_ts": 1683094347
}

Projektion

Wenn berechnete Eigenschaften projiziert werden müssen, muss explizit darauf verwiesen werden. Platzhalterprojektionen wie SELECT * geben alle persistenten Eigenschaften zurück, sie enthalten aber keine berechneten Eigenschaften.

Hier ist eine Beispieldefinition für eine berechnete Eigenschaft, mit der die Eigenschaft name in Kleinbuchstaben konvertiert wird:

{ 
  "name": "cp_lowerName", 
  "query": "SELECT VALUE LOWER(c.name) FROM c" 
}

Diese Eigenschaft kann dann in eine Abfrage projiziert werden:

SELECT 
    c.cp_lowerName 
FROM 
    c

WHERE-Klausel

Auf berechnete Eigenschaften kann wie bei persistenten Eigenschaften in Filterprädikaten verwiesen werden. Wir empfehlen, alle relevanten einzelnen oder zusammengesetzten Indizes hinzuzufügen, wenn Sie berechnete Eigenschaften in Filtern verwenden.

Hier ist eine Beispieldefinition für eine berechnete Eigenschaft, mit der ein Preisnachlass von 20 Prozent berechnet wird:

{ 
  "name": "cp_20PercentDiscount", 
  "query": "SELECT VALUE (c.price * 0.2) FROM c" 
}

Es kann dann nach dieser Eigenschaft gefiltert werden, um sicherzustellen, dass nur Produkte zurückgegeben werden, bei denen der Nachlass weniger als 50 USD beträgt:

SELECT 
    c.price - c.cp_20PercentDiscount as discountedPrice, 
    c.name 
FROM 
    c 
WHERE 
    c.cp_20PercentDiscount < 50.00

GROUP BY-Klausel

Wie bei persistenten Eigenschaften kann auch auf berechnete Eigenschaften in der GROUP BY-Klausel verwiesen werden und der Index wann immer möglich verwendet werden. Fügen Sie alle relevanten einzelnen oder zusammengesetzten Indizes hinzu, um die beste Leistung zu erzielen.

Hier ist eine Beispieldefinition für eine berechnete Eigenschaft, mit der die primäre Kategorie für jedes Element in der Eigenschaft categoryName gesucht wird:

{
  "name": "cp_primaryCategory",
  "query": "SELECT VALUE SUBSTRING(c.categoryName, 0, INDEX_OF(c.categoryName, ',')) FROM c"
}

Anschließend können Sie nach cp_primaryCategory gruppieren, um die Anzahl der Elemente in jeder primären Kategorie zu erhalten:

SELECT 
    COUNT(1), 
    c.cp_primaryCategory 
FROM 
    c 
GROUP BY 
    c.cp_primaryCategory

Tipp

Obgleich Sie diese Abfrage auch ohne die Verwendung berechneter Eigenschaften erstellen können, vereinfachen berechnete Eigenschaften das Schreiben der Abfrage erheblich und ermöglichen eine höhere Leistung, da cp_primaryCategory indiziert werden kann. Sowohl SUBSTRING() als auch INDEX_OF() erfordern eine vollständige Überprüfung aller Elemente im Container, doch wenn Sie die berechnete Eigenschaft indizieren, kann stattdessen die gesamte Abfrage aus dem Index bereitgestellt werden. Die Möglichkeit, die Abfrage aus dem Index bereitzustellen, anstatt eine vollständige Überprüfung durchzuführen, erhöht die Leistung und senkt die Kosten der Abfrageanforderungseinheit (RU).

ORDER BY-Klausel

Wie bei persistenten Eigenschaften kann auch auf berechnete Eigenschaften in der ORDER BY-Klausel verwiesen werden, und sie müssen indiziert werden, damit die Abfrage erfolgreich ist. Mithilfe von berechneten Eigenschaften können Sie das Ergebnis komplexer Logik- oder Systemfunktionen nach Kriterien sortieren (ORDER BY), wodurch Ihnen bei der Nutzung von Azure Cosmos DB viele neue Abfrageszenarien eröffnet werden.

Hier ist eine Beispieldefinition für eine berechnete Eigenschaft, mit der der Monat aus dem Wert _ts abgerufen wird:

{
  "name": "cp_monthUpdated",
  "query": "SELECT VALUE DateTimePart('m', TimestampToDateTime(c._ts*1000)) FROM c"
}

Bevor Sie cp_monthUpdated in einer ORDER BY-Klausel verwenden können, müssen Sie den Wert Ihrer Indizierungsrichtlinie hinzufügen. Nachdem Ihre Indizierungsrichtlinie aktualisiert wurde, können Sie nach der berechneten Eigenschaft sortieren.

SELECT
    *
FROM
    c
ORDER BY
    c.cp_monthUpdated

Indizieren berechneter Eigenschaften

Berechnete Eigenschaften werden standardmäßig nicht indiziert und sind nicht durch Platzhalterpfade in der Indizierungsrichtlinie abgedeckt. Sie können einzelne oder zusammengesetzte Indizes für berechnete Eigenschaften auf die gleiche Weise wie Indizes für persistente Eigenschaften in der Indizierungsrichtlinie hinzufügen. Wir empfehlen, allen berechneten Eigenschaften relevante Indizes hinzuzufügen. Wir empfehlen diese Indizes, da sie sich positiv auf die Leistungssteigerung und die Reduzierung der RUs auswirken, wenn sie indiziert werden. Wenn berechnete Eigenschaften indiziert werden, werden die tatsächlichen Werte während der Schreibvorgänge für Elemente ausgewertet, um Indexbegriffe zu generieren und zu speichern.

Beim Indizieren von berechneten Eigenschaften sind einige Punkte zu beachten, wie beispielsweise:

  • Berechnete Eigenschaften können in eingeschlossenen Pfaden, ausgeschlossenen Pfaden und zusammengesetzten Indexpfaden angegeben werden.
  • Für berechnete Eigenschaften kann kein räumlicher Index definiert sein.
  • Platzhalterpfade unter dem Pfad der berechneten Eigenschaft funktionieren wie bei regulären Eigenschaften.
  • Wenn Sie eine berechnete Eigenschaft entfernen, die indiziert wurde, müssen auch alle Indizes für diese Eigenschaft entfernt werden.

Hinweis

Alle berechneten Eigenschaften werden auf oberster Ebene des Elements definiert. Der Pfad ist immer /<computed property name>.

Tipp

Bei jeder Aktualisierung von Containereigenschaften werden die alten Werte überschrieben. Wenn Sie bereits über berechnete Eigenschaften verfügen und neue hinzufügen möchten, stellen Sie sicher, dass Sie der Sammlung sowohl neue als auch vorhandene berechnete Eigenschaften hinzufügen.

Hinweis

Wenn die Definition einer indizierten berechneten Eigenschaft geändert wird, wird sie nicht automatisch neu indiziert. Um die geänderte berechnete Eigenschaft indizieren zu können, müssen Sie zuerst die berechnete Eigenschaft aus dem Index ablegen. Nachdem die Neuindizierung abgeschlossen wurde, fügen Sie die berechnete Eigenschaft wieder zur Indexrichtlinie hinzu.

Wenn Sie eine berechnete Eigenschaft löschen möchten, müssen Sie sie zuerst aus der Indexrichtlinie entfernen.

Hinzufügen eines einzelnen Indexes für berechnete Eigenschaften

So fügen Sie einen einzelnen Index für eine berechnete Eigenschaft mit dem Namen cp_myComputedProperty hinzu:

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/*"
    },
    {
      "path": "/cp_myComputedProperty/?"
    }
  ],
  "excludedPaths": [
    {
      "path": "/\"_etag\"/?"
    }
  ]
}

Hinzufügen eines zusammengesetzten Indexes für berechnete Eigenschaften

So fügen Sie einen zusammengesetzten Index für zwei Eigenschaften hinzu, wobei eine als cp_myComputedProperty berechnet und die andere als myPersistedProperty beibehalten wird:

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/*"
    }
  ],
  "excludedPaths": [
    {
      "path": "/\"_etag\"/?"
    }
  ],
  "compositeIndexes": [
    [
      {
        "path": "/cp_myComputedProperty"
      },
      {
        "path": "/path/to/myPersistedProperty"
      }
    ]
  ]
}

Grundlegendes zum Verbrauch von Anforderungseinheiten

Beim Hinzufügen berechneter Eigenschaften zu einem Container werden keine RUs verbraucht. Bei Schreibvorgängen für Container, für die berechnete Eigenschaften definiert sind, kann es zu einer leichten Erhöhung der RUs führen. Wenn eine berechnete Eigenschaft indiziert wird, erhöhen sich die RUs für Schreibvorgänge, um die Kosten für die Indizierung und die Auswertung der berechneten Eigenschaft widerzuspiegeln. In der Vorschauphase können sich RU-Gebühren im Zusammenhang mit berechneten Eigenschaften ändern.

Zugehöriger Inhalt