Berechnete Eigenschaften in Azure Cosmos DB für NoSQL

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.

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.

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 beibehaltene 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 nicht deterministischen 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

Nachdem die berechneten Eigenschaften erstellt wurden, können Sie Abfragen ausführen, die mithilfe einer beliebigen Methode auf die Eigenschaften verweisen, einschließlich aller Software Development Kits (SDKs) und Azure Data Explorer im Azure-Portal.

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);

 const { resource: contDefinition } = await containerWithComputedProperty.read();
  const upperName = {
    name: "upperLastName",
    query:
      "SELECT VALUE UPPER(IS_DEFINED(c.lastName) ? c.lastName : c.parents[0].familyName) FROM c",
  };
  if (contDefinition) {
    // update computed properties
    contDefinition.computedProperties = [upperName];
    // replace container definition with updated computed properties
    await containerWithComputedProperty.replace(contDefinition);
    console.log("Computed properties updated");
  } else {
    console.log("Container definition is undefined.");
  }

const lowerName = {
    name: "lowerLastName",
    query:
      "SELECT VALUE LOWER(IS_DEFINED(c.lastName) ? c.lastName : c.parents[0].familyName) FROM c",
};

const { container: containerWithComputedProperty } = await database.containers.createIfNotExists({
  id: containerId,
  computedProperties: [lowerName],
});

computed_properties = [{'name': "cp_lower", 'query': "SELECT VALUE LOWER(c.db_group) FROM c"},
                       {'name': "cp_power", 'query': "SELECT VALUE POWER(c.val, 2) FROM c"},
                       {'name': "cp_str_len", 'query': "SELECT VALUE LENGTH(c.stringProperty) FROM c"}]

container_with_computed_props = db.create_container_if_not_exists(
            "myContainer", PartitionKey(path="/pk"), computed_properties=computed_properties)

queried_items = list(
            container_with_computed_props.query_items(query='Select * from c Where c.cp_power = 25', partition_key="test"))

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);

CosmosContainer container = client.getDatabase("myDatabase").getContainer("myContainer");
// Read the current container properties
CosmosContainerProperties containerProperties = container.read().getProperties();
// Make the necessary updates to the container properties
Collection<ComputedProperty> modifiedComputedProperites = containerProperties.getComputedProperties();
modifiedComputedProperites.add(new ComputedProperty("cp_upperName", "SELECT VALUE UPPER(c.firstName) FROM c"));
containerProperties.setComputedProperties(modifiedComputedProperites);
// Update the container with changes
container.replace(containerProperties);

const { resource: contDefinition } = await containerWithComputedProperty.read();
const upperName = {
name: "upperLastName", query: "SELECT VALUE UPPER(IS_DEFINED(c.lastName) ? c.lastName : c.parents[0].familyName) FROM c",
};
if (contDefinition) {
// update computed properties contDefinition.computedProperties = [upperName]; // replace container definition with updated computed properties await containerWithComputedProperty.replace(contDefinition); console.log("Computed properties updated");
} else {
console.log("Container definition is undefined.");
}

Erstellen berechneter Eigenschaften mithilfe des Daten-Explorers

Sie können den Daten-Explorer verwenden, um eine berechnete Eigenschaft für einen Container zu erstellen.

1. Öffnen Sie ihren vorhandenen Container im Daten-Explorer.

2. Navigieren Sie zum Abschnitt "Einstellungen" für Ihren Container. Navigieren Sie dann zum Unterabschnitt *Computed Properties .

3. Bearbeiten Sie die JSON-Definition der berechneten Eigenschaften für Ihren Container. In diesem Beispiel wird dieser JSON verwendet, um eine berechnete Eigenschaft zu definieren, um die SKU Zeichenfolge für ein Einzelhandelsprodukt mithilfe des - Trennzeichens aufzuteilen.

   [
     {
       "name": "cp_splitSku",
       "query": "SELECT VALUE StringSplit(p.sku, \"-\") FROM products p"
     }
   ]
   

   

4. Speichern Sie die berechnete Eigenschaft.

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.

Hier ist ein Beispiel für ein Element:

{
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "categoryId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "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": "cccccccc-2222-3333-4444-dddddddddddd",
      "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

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 bei der Steigerung der Leistung und der Reduzierung von Anforderungseinheiten (RUs) von Vorteil sind. 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.
• Berechnete Eigenschaften können keinen räumlichen Index definieren.
• Wildcardpfade unter dem berechneten Eigenschaftspfad funktionieren wie bei regulären Eigenschaften
• Verwandte Indizes für eine entfernte und indizierte Eigenschaft müssen ebenfalls gelöscht werden.

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.

Zugehöriger Inhalt

• Verwalten von Indizierungsrichtlinien
• Modelldokumentdaten