Erste Schritte mit SQL-AbfragenGetting started with SQL queries

GILT FÜR: SQL-API

Für Azure Cosmos DB-SQL-API-Konten gibt es zwei Möglichkeiten, Daten zu lesen:In Azure Cosmos DB SQL API accounts, there are two ways to read data:

Punktlesevorgänge: Sie können nach einem Schlüssel/Wert anhand einer einzelnen Element-ID und einem Partitionsschlüssel suchen.Point reads - You can do a key/value lookup on a single item ID and partition key. Die Kombination aus Element-ID und Partitionsschlüssel ist der Schlüssel, und das Element selbst ist der Wert.The item ID and partition key combination is the key and the item itself is the value. Für ein Dokument mit einer Größe von 1 KB erfordern Punktlesevorgänge in der Regel eine Anforderungseinheit mit einer Wartezeit von unter 10 Millisekunden.For a 1 KB document, point reads typically cost 1 request unit with a latency under 10 ms. Lesevorgänge geben ein einzelnes Element zurück.Point reads return a single item.

Hier finden Sie Beispiele für Punktlesevorgänge für die verschiedenen SDKs:Here are some examples of how to do Point reads with each SDK:

SQL-Abfragen: Sie können Daten auch abfragen, indem Sie mit SQL als JSON-Abfragesprache Abfragen schreiben.SQL queries - You can query data by writing queries using the Structured Query Language (SQL) as a JSON query language. Abfragen benötigen immer mindestens 2,3 Anforderungseinheiten. Im Allgemeinen weisen sie auch eine höhere und variablere Wartezeit im Vergleich zu Punktlesevorgängen auf.Queries always cost at least 2.3 request units and, in general, will have a higher and more variable latency than point reads. Abfragen können viele Elemente zurückgeben.Queries can return many items.

Die meisten leseintensiven Workloads in Azure Cosmos DB verwenden eine Kombination von Punktlesevorgängen und SQL-Abfragen.Most read-heavy workloads on Azure Cosmos DB use a combination of both point reads and SQL queries. Wenn Sie nur ein einzelnes Element lesen müssen, sind Punktlesevorgänge günstiger und schneller als Abfragen.If you just need to read a single item, point reads are cheaper and faster than queries. Punktlesevorgänge müssen die Abfrage-Engine nicht verwenden, um auf Daten zuzugreifen, und sie können die Daten direkt lesen.Point reads don't need to use the query engine to access data and can read the data directly. Natürlich ist es nicht für alle Workloads möglich, Daten ausschließlich mithilfe von Punktlesevorgängen zu lesen. Die Unterstützung von SQL als Abfragesprache und die vom Schema unabhängige Indexierung bieten also eine flexiblere Möglichkeit, auf Ihre Daten zuzugreifen.Of course, it's not possible for all workloads to exclusively read data using point reads, so support of SQL as a query language and schema-agnostic indexing provide a more flexible way to access your data.

Hier finden Sie Beispiele für SQL-Abfragen für die verschiedenen SDKs:Here are some examples of how to do SQL queries with each SDK:

Im verbleibenden Teil dieser Dokumentation erfahren Sie, wie Sie SQL-Abfragen in Azure Cosmos DB schreiben.The remainder of this doc shows how to get started writing SQL queries in Azure Cosmos DB. SQL-Abfragen können entweder über das SDK oder das Azure-Portal ausgeführt werden.SQL queries can be run through either the SDK or Azure portal.

Hochladen von BeispieldatenUpload sample data

Öffnen Sie in Ihrem Cosmos DB-Konto der SQL-API den Data Explorer, um einen Container mit dem Namen Families zu erstellen.In your SQL API Cosmos DB account, open the Data Explorer to create a container called Families. Verwenden Sie nach dem Erstellen den Datenstrukturbrowser, um ihn zu suchen und zu öffnen.After the it is created, use the data structures browser, to find and open it. In Ihrem Families-Container wird die Option Items direkt unterhalb des Namens des Containers angezeigt.In your Families container, you will see the Items option right below the name of the container. Öffnen Sie diese Option. Daraufhin wird auf der Menüleiste in der Mitte des Bildschirms eine Schaltfläche angezeigt, mit der Sie ein neues Element erstellen können.Open this option and you'll see a button, in the menu bar in center of the screen, to create a 'New Item'. Sie verwenden diese Funktion, um die folgenden JSON-Elemente zu erstellen.You will use this feature to create the JSON items below.

Erstellen von JSON-ElementenCreate JSON items

Die folgenden beiden JSON-Elemente sind Dokumente zu den Familien „Andersen“ und „Wakefield“.The following 2 JSON items are documents about the Andersen and Wakefield families. Sie enthalten Eltern, Kinder, Haustiere, Adresse und Registrierungsinformationen.They include parents, children and their pets, address, and registration information.

Das erste Element enthält Zeichenfolgen, Zahlen, boolesche Werte, Arrays und geschachtelte Eigenschaften:The first item has strings, numbers, Booleans, arrays, and nested properties:

{
  "id": "AndersenFamily",
  "lastName": "Andersen",
  "parents": [
     { "firstName": "Thomas" },
     { "firstName": "Mary Kay"}
  ],
  "children": [
     {
         "firstName": "Henriette Thaulow",
         "gender": "female",
         "grade": 5,
         "pets": [{ "givenName": "Fluffy" }]
     }
  ],
  "address": { "state": "WA", "county": "King", "city": "Seattle" },
  "creationDate": 1431620472,
  "isRegistered": true
}

Das zweite Element verwendet givenName und familyName anstelle von firstName und lastName:The second item uses givenName and familyName instead of firstName and lastName:

{
  "id": "WakefieldFamily",
  "parents": [
      { "familyName": "Wakefield", "givenName": "Robin" },
      { "familyName": "Miller", "givenName": "Ben" }
  ],
  "children": [
      {
        "familyName": "Merriam",
        "givenName": "Jesse",
        "gender": "female",
        "grade": 1,
        "pets": [
            { "givenName": "Goofy" },
            { "givenName": "Shadow" }
        ]
      },
      {
        "familyName": "Miller",
         "givenName": "Lisa",
         "gender": "female",
         "grade": 8 }
  ],
  "address": { "state": "NY", "county": "Manhattan", "city": "NY" },
  "creationDate": 1431620462,
  "isRegistered": false
}

Abfragen der JSON-ElementeQuery the JSON items

Führen Sie einige Abfragen für die JSON-Daten aus, um einige der Schlüsselaspekte der SQL-Abfragesprache von Azure Cosmos DB besser zu verstehen.Try a few queries against the JSON data to understand some of the key aspects of Azure Cosmos DB's SQL query language.

Die folgende Abfrage gibt die Elemente zurück, in denen das id-Feld dem Text AndersenFamily entspricht.The following query returns the items where the id field matches AndersenFamily. Da es sich um eine SELECT *-Abfrage handelt, ist die Ausgabe der Abfrage das komplette JSON-Element.Since it's a SELECT * query, the output of the query is the complete JSON item. Weitere Informationen zur SELECT-Syntax finden Sie unter SELECT-Anweisung.For more information about SELECT syntax, see SELECT statement.

    SELECT *
    FROM Families f
    WHERE f.id = "AndersenFamily"

Die Abfrage hat folgende Ergebnisse:The query results are:

    [{
        "id": "AndersenFamily",
        "lastName": "Andersen",
        "parents": [
           { "firstName": "Thomas" },
           { "firstName": "Mary Kay"}
        ],
        "children": [
           {
               "firstName": "Henriette Thaulow", "gender": "female", "grade": 5,
               "pets": [{ "givenName": "Fluffy" }]
           }
        ],
        "address": { "state": "WA", "county": "King", "city": "Seattle" },
        "creationDate": 1431620472,
        "isRegistered": true
    }]

Mit der folgenden Abfrage wird die JSON-Ausgabe auf andere Weise neu formatiert.The following query reformats the JSON output into a different shape. Die Abfrage projiziert ein neues JSON-Objekt Family mit zwei ausgewählten Feldern (Name und City), wenn die Stadt in der Adresse dem Staat entspricht.The query projects a new JSON Family object with two selected fields, Name and City, when the address city is the same as the state. Dies ist bei „NY, NY“ der Fall."NY, NY" matches this case.

    SELECT {"Name":f.id, "City":f.address.city} AS Family
    FROM Families f
    WHERE f.address.city = f.address.state

Die Abfrage hat folgende Ergebnisse:The query results are:

    [{
        "Family": {
            "Name": "WakefieldFamily",
            "City": "NY"
        }
    }]

Die folgende Abfrage gibt alle Vornamen von Kindern der Familie zurück, deren id dem Text WakefieldFamily entspricht, und zwar geordnet nach der Stadt.The following query returns all the given names of children in the family whose id matches WakefieldFamily, ordered by city.

    SELECT c.givenName
    FROM Families f
    JOIN c IN f.children
    WHERE f.id = 'WakefieldFamily'
    ORDER BY f.address.city ASC

Die Ergebnisse sind:The results are:

    [
      { "givenName": "Jesse" },
      { "givenName": "Lisa"}
    ]

BemerkungenRemarks

Die Beispiele oben zeigen verschiedene Aspekte der Cosmos DB-Abfragesprache:The preceding examples show several aspects of the Cosmos DB query language:

  • Da die SQL-API mit JSON-Werten arbeitet, werden baumförmige Entitäten anstelle von Spalten und Zeilen verarbeitet.Since SQL API works on JSON values, it deals with tree-shaped entities instead of rows and columns. Sie können auf die Baumknoten in beliebiger Tiefe verweisen, z.B. Node1.Node2.Node3…..Nodem, ähnlich dem zweiteiligen Verweis <table>.<column> in ANSI SQL.You can refer to the tree nodes at any arbitrary depth, like Node1.Node2.Node3…..Nodem, similar to the two-part reference of <table>.<column> in ANSI SQL.

  • Da die Abfragesprache mit schemalosen Daten arbeitet, muss das Typsystem dynamisch gebunden werden.Because the query language works with schemaless data, the type system must be bound dynamically. Der gleiche Ausdruck kann unterschiedliche Typen in unterschiedlichen Elementen ergeben.The same expression could yield different types on different items. Das Ergebnis einer Abfrage ist ein gültiger JSON-Wert, aber nicht garantiert innerhalb eines festen Schemas.The result of a query is a valid JSON value, but isn't guaranteed to be of a fixed schema.

  • Azure Cosmos DB unterstützt nur strikte JSON-Elemente.Azure Cosmos DB supports strict JSON items only. Typsystem und Ausdrücke sind auf JSON-Typen beschränkt.The type system and expressions are restricted to deal only with JSON types. Weitere Informationen finden Sie in der JSON-Spezifikation.For more information, see the JSON specification.

  • Ein Cosmos-Container ist eine schemalose Sammlung von JSON-Elementen.A Cosmos container is a schema-free collection of JSON items. Die Beziehungen innerhalb und zwischen Containerelementen werden implizit nach Eigenständigkeit erfasst, nicht nach Beziehungen von primären Schlüsseln und Fremdschlüsseln.The relations within and across container items are implicitly captured by containment, not by primary key and foreign key relations. Dieses Feature ist für die elementinternen Verknüpfungen wichtig, die in Verknüpfungen in Azure Cosmos DBbeschrieben werden.This feature is important for the intra-item joins that are described in Joins in Azure Cosmos DB.

Nächste SchritteNext steps