Introducción a las consultas SQLGetting started with SQL queries

Las cuentas de la API SQL para Azure Cosmos DB admiten la realización de consultas mediante el Lenguaje de consulta estructurado (SQL) como lenguaje de consulta de JSON.Azure Cosmos DB SQL API accounts support querying items using Structured Query Language (SQL) as a JSON query language. Los objetivos de diseño del lenguaje de consulta de Azure Cosmos DB son:The design goals of the Azure Cosmos DB query language are to:

  • Admitir SQL, uno de los lenguajes de consulta más conocidos, en lugar de inventar uno nuevo.Support SQL, one of the most familiar and popular query languages, instead of inventing a new query language. SQL proporciona un modelo de programación formal para consultas enriquecidas a través de elementos JSON.SQL provides a formal programming model for rich queries over JSON items.

  • Usar el modelo de programación de JavaScript como base para el lenguaje de consulta.Use JavaScript's programming model as the foundation for the query language. El sistema de tipos de JavaScript, la evaluación de expresiones y la invocación de funciones son las bases de la API de SQL.JavaScript's type system, expression evaluation, and function invocation are the roots of the SQL API. Estas bases proporcionan un modelo de programación natural para características como las proyecciones relacionales, la navegación jerárquica por elementos JSON, autocombinaciones, las consultas espaciales y la invocación de funciones definidas por el usuario (UDF) escritas íntegramente en JavaScript.These roots provide a natural programming model for features like relational projections, hierarchical navigation across JSON items, self-joins, spatial queries, and invocation of user-defined functions (UDFs) written entirely in JavaScript.

Cargar datos de ejemploUpload sample data

En la cuenta de la API de SQL para Cosmos DB, cree un contenedor denominado Families.In your SQL API Cosmos DB account, create a container called Families. Cree dos elementos JSON sencillos en el contenedor.Create two simple JSON items in the container. Puede ejecutar la mayoría de las consultas de ejemplo en la documentación de consultas de Azure Cosmos DB con este conjunto de datos.You can run most of the sample queries in the Azure Cosmos DB query docs using this data set.

Creación de elementos JSONCreate JSON items

Con el siguiente código se crean dos elementos JSON sencillos sobre familias.The following code creates two simple JSON items about families. Los elementos JSON sencillos para las familias Andersen y Wakefield incluyen a los padres, los hijos, sus mascotas, la dirección y la información de registro.The simple JSON items for the Andersen and Wakefield families include parents, children and their pets, address, and registration information. El primer elemento tiene cadenas, números, valores booleanos, matrices y propiedades anidadas.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
}

El segundo elemento usa givenName y familyName en lugar de firstName y 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
}

Consulta de los elementos JSONQuery the JSON items

Pruebe algunas consultas con los datos JSON para entender algunos aspectos clave del lenguaje de consulta SQL de Azure Cosmos DB.Try a few queries against the JSON data to understand some of the key aspects of Azure Cosmos DB's SQL query language.

La consulta siguiente devuelve los elementos en los que el campo id coincide con AndersenFamily.The following query returns the items where the id field matches AndersenFamily. Puesto que es una consulta SELECT *, la salida de la consulta es el elemento JSON completo.Since it's a SELECT * query, the output of the query is the complete JSON item. Para más información sobre la sintaxis de SELECT, consulte Instrucción SELECT.For more information about SELECT syntax, see SELECT statement.

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

Los resultados de la consulta son: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
    }]

La siguiente consulta vuelve a formatear la salida JSON en una forma diferente.The following query reformats the JSON output into a different shape. La consulta proyecta un nuevo objeto JSON Family con dos campos seleccionados, Name y City, cuando la ciudad de la dirección es la misma que el estado.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. "NY, NY" coincide con esto."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

Los resultados de la consulta son:The query results are:

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

La consulta siguiente devuelve todos los nombres proporcionados de los hijos de la familia cuyo id coincide con WakefieldFamily, ordenados por ciudad.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

Los resultados son:The results are:

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

ObservacionesRemarks

Los ejemplos anteriores muestran varios aspectos del lenguaje de consulta de Cosmos DB:The preceding examples show several aspects of the Cosmos DB query language:

  • Como la API de SQL trabaja en valores JSON, trata con entidades en forma de árbol en lugar de con filas y columnas.Since SQL API works on JSON values, it deals with tree-shaped entities instead of rows and columns. Puede hacer referencia a los nodos de árbol de cualquier profundidad arbitraria, como Node1.Node2.Node3…..Nodem, de forma similar a la referencia de dos partes de <table>.<column> en SQL ANSI.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.

  • Dado que el lenguaje de consulta funciona con datos sin esquema, el sistema de tipos debe enlazarse dinámicamente.Because the query language works with schemaless data, the type system must be bound dynamically. La misma expresión podría generar diversos tipos en distintos elementos.The same expression could yield different types on different items. El resultado de una consulta es un valor JSON válido, pero no se garantiza que sea de un esquema fijo.The result of a query is a valid JSON value, but isn't guaranteed to be of a fixed schema.

  • Azure Cosmos DB solo admite elementos JSON estrictos.Azure Cosmos DB supports strict JSON items only. El sistema de tipos y las expresiones se restringen para tratar únicamente con tipos JSON.The type system and expressions are restricted to deal only with JSON types. Para más información, consulte la especificación de JSON.For more information, see the JSON specification.

  • Un contenedor de Cosmos es una colección sin esquemas de elementos JSON.A Cosmos container is a schema-free collection of JSON items. Las relaciones tanto dentro de los elementos de un contenedor como entre ellos se capturan de manera implícita por independencia, no por las relaciones entre la clave principal y la clave externa.The relations within and across container items are implicitly captured by containment, not by primary key and foreign key relations. Esta característica es importante para las combinaciones dentro del elemento descritas más adelante en este artículo.This feature is important for the intra-item joins discussed later in this article.

Pasos siguientesNext steps