Referencia del lenguaje de consulta de Azure Digital Twins: cláusula MATCH

Este documento contiene información de referencia sobre la cláusula MATCH para el lenguaje de consulta de Azure Digital Twins.

La cláusula MATCH se usa en el lenguaje de consulta de Azure Digital Twins como parte de la cláusula FROM. MATCH permite especificar el patrón que debe seguirse al recorrer las relaciones en el grafo de Azure Digital Twins. Esto se conoce también como patrón de consulta de "salto variable".

Esta cláusula es opcional durante la consulta.

Sintaxis básica: MATCH

MATCH admite cualquier consulta que busque una ruta de acceso entre gemelos dentro de un intervalo de saltos, según determinadas condiciones de relación.

Una condición de relación puede incluir uno o varios de los siguientes datos:

• Dirección de la relación (de izquierda a derecha, de derecha a izquierda o no direccional).
• Nombre de la relación (un nombre único o una lista de posibilidades).
• Número de "saltos" de un gemelo a otro (un número exacto o un intervalo).
• Una asignación de variable de consulta para representar la relación en el texto de la consulta. Esto también permite filtrar por las propiedades de la relación.

Una consulta con una cláusula MATCH también debe usar la cláusula WHERE para especificar el elemento $dtId de al menos uno de los gemelos a los que hace referencia.

Sintaxis

Ésta es la sintaxis de MATCH básica.

Contiene estos marcadores de posición:

• twin_or_twin_collection (x2): la cláusula MATCH requiere un operando para representar un único gemelo. El otro operando puede representar otro gemelo único o una colección de gemelos.
• relationship_condition: en este espacio, defina una condición que describa la relación entre los gemelos o las colecciones de gemelos. La condición puede especificar la dirección de la relación, especificar el nombre de la relación, especificar el número de saltos, especificar las propiedades de la relación o cualquier combinación de estas opciones.
• twin_ID: aquí, especifique un valor de $dtId dentro de una de las colecciones de gemelos para que uno de los operandos represente un único gemelo.

--SELECT ... FROM ...  
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)
WHERE twin_or_twin_collection.$dtId = 'twin_ID' 
-- AND ...

Puede dejar en blanco una de las colecciones de gemelos para permitir que cualquier gemelo funcione en ese lugar.

También puede cambiar el número de condiciones de relación para tener varias condiciones encadenadas o ninguna condición de relación:

--Chained relationship conditions
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)-[relationship_condition]-(twin_or_twin_collection_3)...
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

-- No relationship condition
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

Para obtener más información sobre cada tipo de condición de relación y cómo combinarlos, consulte las demás secciones de este documento.

Ejemplo

Esta es una consulta de ejemplo donde se utiliza MATCH.

La consulta especifica una dirección de relación y busca los gemelos Building y Sensor donde...

• Sensor es el objetivo de cualquier relación de un gemelo Building con un $dtId de Building21 y
• el sensor tiene una temperatura superior a 50. Building y Sensor se incluyen en el resultado de la consulta.

SELECT Building, Sensor FROM DIGITALTWINS 
MATCH (Building)-[]->(Sensor) 
WHERE Building.$dtId = 'Building21' AND Sensor.temperature > 50

Especificación de la dirección de la relación

Use la condición de relación de la cláusula MATCH para especificar una dirección de relación entre los gemelos. Las direcciones posibles incluyen son de izquierda a derecha, de derecha a izquierda o no direccional. Las relaciones cíclicas se detectan automáticamente, de modo que una relación se recorre solo una vez.

Sintaxis

Las descripciones de relaciones direccionales usan una representación visual de una flecha para indicar la dirección de la relación. La flecha incluye un espacio delimitado por corchetes ([]) para un nombre de relación opcional.

En esta sección, se muestra la sintaxis de distintas direcciones de las relaciones. Los valores de marcador de posición que deben reemplazarse por sus valores son source_twin_or_twin_collection y target_twin_or_twin_collection.

Para una relación de izquierda a derecha, utilice la siguiente sintaxis.

-- SELECT ... FROM ...
MATCH (source_twin_or_twin_collection)-[]->(target_twin_or_twin_collection)
-- WHERE ...

Para una relación de derecha a izquierda, utilice la siguiente sintaxis.

-- SELECT ... FROM ...
MATCH (target_twin_or_twin_collection)<-[]-(source_twin_or_twin_collection)
-- WHERE ...

Para una relación no direccional, utilice la siguiente sintaxis. Esto no especificará una dirección para la relación, por lo que se incluirán en el resultado las relaciones de cualquier dirección.

-- SELECT ... FROM ...
MATCH (source_twin_or_twin_collection)-[]-(target_twin_or_twin_collection)
-- WHERE ...

Ejemplos

En el primer ejemplo, se muestra un recorrido direccional de izquierda a derecha. Esta consulta busca los gemelos Room y Factory, donde...

• Room tiene Factory como destino (con cualquier nombre de relación);
• Room tiene un valor de temperatura superior a 50;
• Factory tiene un $dtId de "ABC".

SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)-[]->(Factory) 
WHERE Room.temperature > 50 AND Factory.$dtId = 'ABC'

En el ejemplo siguiente, se muestra un recorrido direccional de derecha a izquierda. Esta consulta es similar a la anterior, pero se invierte la dirección de la relación entre Room y Factory. Esta consulta busca los gemelos Room y Factory, donde...

• Factory tiene Room como destino (con cualquier nombre de relación);
• Factory tiene un $dtId de "ABC".
• Room tiene un valor de temperatura superior a 50;

SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)<-[]-(Factory) 
WHERE Factory.$dtId = 'ABC' AND Room.temperature > 50

En el ejemplo siguiente, se muestra un recorrido no direccional. Esta consulta busca los gemelos Room y Factory, donde...

• Room y Factory comparten cualquier nombre de relación, en cualquier dirección;
• Factory tiene un $dtId de "ABC".
• Room tiene un valor de humedad superior a 70.

SELECT Factory, Room FROM DIGITALTWINS MATCH (Factory)-[]-(Room) 
WHERE Factory.$dtId ='ABC'  AND Room.humidity > 70

Especificación del nombre de la relación

Opcionalmente, puede usar la condición de relación de la cláusula MATCH para especificar nombres para las relaciones entre los gemelos. Puede especificar un único nombre o una lista de posibles nombres. El nombre de relación opcional se incluye como parte de la sintaxis de flecha para especificar la dirección de la relación.

Si no proporciona un nombre de relación, la consulta incluye todos los nombres de relación de forma predeterminada.

Sintaxis

Especifique el nombre de una relación para recorrerla en la cláusula MATCH entre corchetes ([]) después de dos puntos (:). En esta sección, se muestra la sintaxis para especificar relaciones con nombre.

Para un único nombre, utilice la siguiente sintaxis. Los valores de marcador de posición que deben reemplazarse por sus valores son twin_or_twin_collection_1, relationship_name y twin_or_twin_collection_2.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[:relationship_name]-(twin_or_twin_collection_2)
-- WHERE ...

Para varios nombres posibles, utilice la siguiente sintaxis. Los valores de marcador de posición que deben reemplazarse por sus valores son twin_or_twin_collection_1, relationship_name_option_1, relationship_name_option_2, twin_or_twin_collection_2 y la nota para continuar el patrón según sea necesario para el número de nombres de relación que desee especificar.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[:relationship_name_option_1|relationship_name_option_2|continue pattern as needed...]-(twin_or_twin_collection_2)
-- WHERE ...

(Valor predeterminado) Para dejar el nombre sin especificar, deje los corchetes vacíos, sin información de nombre, de la siguiente forma:

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[]-(twin_or_twin_collection_2)
-- WHERE ...

Ejemplos

En el ejemplo siguiente, se muestra un único nombre de relación. Esta consulta busca los gemelos Building y Sensor, donde...

• Building tiene una relación "contains" con Sensor (en cualquier dirección);
• Building tiene un $dtId de "Seattle21".

SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

En el ejemplo siguiente, se muestran varios nombres de relación posibles. Esta consulta es similar a la anterior, pero hay varios nombres de relación posibles que se incluyen en el resultado. Esta consulta busca los gemelos Building y Sensor, donde...

• Building tiene una relación "contains" o "isAssociatedWith" con Sensor (en cualquier dirección);
• Building tiene un $dtId de "Seattle21".

SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains|isAssociatedWith]-(Sensor)  
WHERE building.$dtId = 'Seattle21'

En el ejemplo siguiente, no se especifica ningún nombre de relación. Como resultado, se incluirán las relaciones con cualquier nombre en el resultado de la consulta. Esta consulta busca los gemelos Building y Sensor, donde...

• Building tiene una relación con Sensor con cualquier nombre (y en cualquier dirección);
• Building tiene un $dtId de "Seattle21".

SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building-[]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

Especificación del número de saltos

Opcionalmente, puede usar la condición de relación de la cláusula MATCH para especificar el número de saltos de las relaciones entre los gemelos. Puede especificar un número exacto o un intervalo. Este valor opcional se incluye como parte de la sintaxis de flecha para especificar la dirección de la relación.

Si no proporciona un número de saltos, la consulta tendrá como valor predeterminado un salto.

Sintaxis

Especifique el número de saltos que se recorrerán en la cláusula MATCH entre corchetes ([]).

Para especificar un número exacto de saltos, utilice la siguiente sintaxis. Los valores de marcador de posición que deben reemplazarse por sus valores son twin_or_twin_collection_1, number_of_hops y twin_or_twin_collection_2.

-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[*number_of_hops]-(twin_or_twin_collection_2)
-- WHERE ...

Para especificar un intervalo de saltos, utilice la siguiente sintaxis. Los valores de marcador de posición que deben reemplazarse por sus valores son twin_or_twin_collection_1, starting_limit, ending_limit y twin_or_twin_collection_2. El límite inicial no se incluye en el intervalo, mientras que el límite final sí se incluye.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[*starting_limit..ending_limit]-(twin_or_twin_collection_2)
-- WHERE ...

También puede omitir el límite inicial para indicar "cualquier cosa hasta" (e incluyendo) el límite final. Siempre debe proporcionarse un límite final.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)-[*..ending_limit]-(twin_or_twin_collection_2)
-- WHERE ...

(Valor predeterminado) Para usar el valor predeterminado de un salto, deje los corchetes vacíos, sin información de saltos, de la siguiente manera:

-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[]-(twin_or_twin_collection_2)
-- WHERE ...

Ejemplos

En el ejemplo siguiente, se especifica un número exacto de saltos. La consulta solo devolverá las relaciones entre los gemelos Floor y Room que tengan exactamente 3 saltos.

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*3]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

En el ejemplo siguiente, se especifica un intervalo de saltos. La consulta devolverá las relaciones entre los gemelos Floor y Room que tengan entre 1 y 3 saltos (lo que significa que el número de saltos es 2 o 3).

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*1..3]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

También puede mostrar un intervalo proporcionando solo un límite. En el ejemplo siguiente, la consulta devolverá las relaciones entre los gemelos Floor y Room que tengan, como máximo, 2 saltos (lo que significa que el número de saltos es 1 o 2).

SELECT Floor, Room FROM DIGITALTWINS 
MATCH (Floor)-[*..2]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

En el ejemplo siguiente, no se especifica el número de saltos, por lo que se usará el valor predeterminado de un salto entre los gemelos Floor y Room.

SELECT Floor, Room FROM DIGITALTWINS  
MATCH (Floor)-[]-(Room)
WHERE Floor.$dtId = 'thermostat-15'

Asignación de una variable de consulta a una relación (y especificación de propiedades de relación)

Opcionalmente, puede asignar una variable de consulta a la relación a la que se hace referencia en la cláusula MATCH, de modo que podrá hacer referencia a ella por nombre en el texto de la consulta.

Una ventaja de hacer esto es la capacidad de filtrar por las propiedades de la relación en la cláusula WHERE.

Sintaxis

Para asignar una variable de consulta a la relación, ponga el nombre de la variable entre corchetes ([]). Los valores de marcador de posición que deben reemplazarse por sus valores son twin_or_twin_collection_1, relationship_variable y twin_or_twin_collection_2.

-- SELECT ... FROM ...   
MATCH (twin_or_twin_collection_1)-[relationship_variable]-(twin_or_twin_collection_2>) 
-- WHERE ...

Ejemplos

En el ejemplo siguiente, se asigna una variable de consulta "Rel" a la relación. Más adelante, en la cláusula WHERE, se utiliza la variable para especificar que la relación Rel debe tener una propiedad name con el valor "child".

SELECT Floor,Cafe, Rel DIGITALTWINS   
MATCH (Floor)-[Rel]-(Cafe)  
WHERE Floor.$dtId = 'thermostat-15' AND Rel.name = 'child'

Combinación de operaciones MATCH

Puede combinar varias condiciones de relación en la misma consulta. También puede encadenar varias condiciones de relación para expresar relaciones bidireccionales u otras combinaciones más grandes.

Sintaxis

En una sola consulta, puede combinar la dirección de la relación, el nombre de la relación y, o bien el número de saltos, o bien una asignación de variable de consulta.

En los ejemplos de sintaxis siguientes, se muestra cómo se pueden combinar estos atributos. También puede omitir cualquiera de los detalles opcionales que se muestran en los marcadores de posición para omitir esa parte de la condición.

Para especificar la dirección de la relación, el nombre de la relación y el número de saltos en una sola consulta, utilice la siguiente sintaxis en la condición de relación. Los valores de marcador de posición que deben reemplazarse por sus valores son twin_or_twin_collection_1 y twin_or_twin_collection_2, optional_left_angle_bracket y optional_right_angle_bracket, relationship_name(s) y number_of_hops.

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)optional_left_angle_bracket-[:relationship_name(s)*number_of_hops]-optional_right_angle_bracket(twin_or_twin_collection_2)
-- WHERE

Para especificar la dirección de la relación, el nombre de la relación y una variable de consulta para la relación en una sola consulta, utilice la siguiente sintaxis en la condición de relación. Los valores de marcador de posición que deben reemplazarse por sus valores son twin_or_twin_collection_1 y twin_or_twin_collection_2, optional_left_angle_bracket y optional_right_angle_bracket, relationship_variable y relationship_name(s).

-- SELECT ... FROM ...
MATCH (twin_or_twin_collection_1)optional_left_angle_bracket-[relationship_variable:relationship_name(s)]-optional_right_angle_bracket(twin_or_twin_collection_2)
-- WHERE

Puede encadenar varias condiciones de relación como se muestra a continuación. Los valores de marcador de posición que deben reemplazarse por sus valores son twin_or_twin_collection_1, todas las instancias de relationship_condition y twin_or_twin_collection_2.

--Chained relationship conditions
-- SELECT ... FROM ... 
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)-[relationship_condition]-(twin_or_twin_collection_3)...
WHERE twin_or_twin_collection.$dtId = 'twin_ID'

Ejemplos

Este es un ejemplo que combina la dirección de la relación, el nombre de la relación y el número de saltos. En la siguiente consulta, se buscan los gemelos Floor y Room, donde la relación entre ellos cumple estas condiciones:

• la relación es de izquierda a derecha, con Floor como origen y Room como destino;
• la relación tiene el nombre "contains" o "isAssociatedWith";
• la relación tiene 4 o 5 saltos.

La consulta también especifica que el gemelo Floor tiene un $dtId de "thermostat-15".

SELECT Floor, Room FROM DIGITALTWINS    
MATCH (Floor)-[:contains|isAssociatedWith*3..5]->(Room) 
WHERE Floor.$dtId = 'thermostat-15'

Este es un ejemplo donde se combinan la dirección de la relación, el nombre de la relación y una variable de consulta con nombre para la relación. En la siguiente consulta, se buscan los gemelos Floor y Room, donde se asigna la relación entre Floor y Room a una variable de consulta r y se cumplen estas condiciones:

• la relación es de izquierda a derecha, con Floor como origen y Room como destino;
• la relación tiene el nombre "contains" o "isAssociatedWith";
• la relación, a la que se le da una variable de consulta r, tiene una propiedad length igual a 10;

La consulta también especifica que el gemelo Floor tiene un $dtId de "thermostat-15".

SELECT Floor, Room FROM DIGITALTWINS    
MATCH (Floor)-[r:contains|isAssociatedWith]->(Room) 
WHERE Floor.$dtId = 'thermostat-15' AND r.length = 10

En el ejemplo siguiente, se muestran condiciones de relación encadenadas. La consulta busca los gemelos Floor, Cafe y Room, donde...

• la relación entre Floor y Room cumple estas condiciones:
  • la relación es de izquierda a derecha, con Floor como origen y Cafe como destino;
  • la relación tiene el nombre "contains" o "isAssociatedWith";
  • la relación, a la que se le da la variable de consulta r, tiene una propiedad length igual a 10.
• la relación entre Cafe y Room cumple estas condiciones:
  • la relación es de derecha a izquierda, con Room como origen y Café como destino;
  • la relación tiene el nombre "has" o "includes";
  • la relación tiene un máximo de 3 saltos, es decir, 1, 2 o 3 saltos.

La consulta también especifica que el gemelo Floor tiene un $dtId de "thermostat-15" y el gemelo Cafe tiene una temperatura de 55.

SELECT Floor,Room, Cafe FROM DIGITALTWINS    
MATCH (Floor)-[r:contains|isAssociatedWith]->(Cafe)<-[has|includes*..3]-(Room)  
WHERE Floor.$dtId = 'thermostat-15'  AND r.length = 10 AND Cafe.temperature = 55

También puede usar condiciones de relación encadenadas para expresar relaciones bidireccionales. La siguiente consulta busca los gemelos Floor, Room y Building, donde...

• la relación entre Building y Floor cumple estas condiciones:
  • la relación es de izquierda a derecha, con Building como origen y Floor como destino;
  • la relación tiene el nombre "isAssociatedWith";
  • a la relación se le da una variable de consulta r1.
• la relación entre Floor y Room cumple estas condiciones:
  • la relación es de derecha a izquierda, con Room como origen y Floor como destino;
  • la relación tiene el nombre "isAssociatedWith";
  • a la relación se le da una variable de consulta r2.

La consulta también especifica que el gemelo Building tiene un $dtId de "building-3" y el gemelo Room tiene una temperatura superior a 50.

SELECT Floor, Room, Building FROM DIGITALTWINS    
MATCH (Building)-[r1:isAssociatedWith]->(Floor)<-[r2:isAssociatedWith]-(Room)
WHERE Building.$dtId = 'building-3'  AND Room.temperature > 50

Limitaciones

Los límites siguientes se aplican a las consultas que utilizan MATCH:

• Solo se admite una expresión MATCH por instrucción de consulta.

• Se requiere $dtId en la cláusula WHERE.

• La asignación de una variable de consulta a la relación se permite solamente cuando la consulta especifica un único salto.

• El número máximo de saltos admitidos en una consulta es 10.

• Las consultas MATCH que contienen filtros $dtId en cualquier gemelo distinto del gemelo inicial para el MATCH transversal pueden mostrar resultados vacíos. Por ejemplo, la consulta siguiente está sujeta a esta limitación:

  SELECT A, B, C FROM DIGITALTWINS 
  MATCH A-[contains]->B-[is_part_of]->C 
  WHERE B.$dtId = 'Device01'
  

  Si el escenario requiere que use $dtId en otros gemelos, considere la posibilidad de usar la cláusula JOIN en su lugar.

• Las consultas MATCH que atraviesan el mismo gemelo varias veces pueden quitar inesperadamente este gemelo de los resultados.