Referência de linguagem de consulta do Azure Digital Twins: cláusula MATCH

Este documento contém informações de referência sobre a cláusula MATCH para a linguagem de consulta dos Gêmeos Digitais do Azure.

A MATCH cláusula é usada na linguagem de consulta do Azure Digital Twins como parte da cláusula FROM. MATCH permite especificar qual padrão deve ser seguido ao percorrer relacionamentos no gráfico de Gêmeos Digitais do Azure (isso também é conhecido como um padrão de consulta de "salto variável").

Esta cláusula é opcional durante a consulta.

Sintaxe principal: MATCH

MATCH suporta qualquer consulta que encontre um caminho entre gêmeos dentro de um intervalo de saltos, com base em determinadas condições de relacionamento.

A condição de relacionamento pode incluir um ou mais dos seguintes detalhes:

• Direção do relacionamento (da esquerda para a direita, da direita para a esquerda ou não direcional)
• nome do relacionamento (nome único ou uma lista de possibilidades)
• Número de "lúpulos" de um gémeo para outro (número exato ou intervalo)
• Uma atribuição de variável de consulta para representar a relação dentro do texto da consulta. Isso também permitirá que você filtre as propriedades de relacionamento.

Uma consulta com uma MATCH cláusula também deve usar a cláusula WHERE para especificar o $dtId para pelo menos um dos gêmeos aos quais ela faz referência.

Sintaxe

Aqui está a sintaxe básica MATCH .

Ele contém estes espaços reservados:

• twin_or_twin_collection (x2): A MATCH cláusula requer um operando para representar um único gêmeo. O outro operando pode representar outro gêmeo solteiro, ou uma coleção de gêmeos.
• relationship_condition: Neste espaço, defina uma condição que descreva a relação entre as coleções de gêmeos ou gêmeos. A condição pode especificar a direção do relacionamento, especificar o nome do relacionamento, especificar o número de saltos, especificar propriedades do relacionamento ou qualquer combinação dessas opções.
• twin_ID: Aqui, especifique um $dtId dentro de uma das coleções de gêmeos para que um dos operandos represente um único gêmeo.

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

Você pode deixar uma das coleções de gêmeos em branco para permitir que qualquer gêmeo trabalhe nesse local.

Você também pode alterar o número de condições de relacionamento, para ter várias condições de relacionamento encadeadas ou nenhuma condição de relacionamento:

--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 obter mais detalhes sobre cada tipo de condição de relacionamento e como combiná-los, consulte as outras seções deste documento.

Exemplo

Aqui está um exemplo de consulta usando MATCHo .

A consulta especifica uma direção de relacionamento e procura por gêmeos Building e Sensor onde...

• o Sensor é alvo de qualquer relação de um Edifício twin com um $dtId de Building21, e
• o sensor tem uma temperatura acima de 50. O Edifício e o Sensor estão incluídos no resultado da consulta.

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

Especificar a direção do relacionamento

Use a condição de relacionamento na MATCH cláusula para especificar uma direção de relacionamento entre os gêmeos. As direções possíveis incluem da esquerda para a direita, da direita para a esquerda ou não direcional. As relações cíclicas são detetadas automaticamente, de modo que uma relação é percorrida apenas uma vez.

Sintaxe

As descrições de relacionamento direcional usam uma representação visual de uma seta para indicar a direção do relacionamento. A seta inclui um espaço reservado por colchetes ([]) para um nome de relacionamento opcional.

Esta seção mostra a sintaxe para diferentes direções de relacionamentos. Os valores de espaço reservado que devem ser substituídos pelos seus valores são source_twin_or_twin_collection e target_twin_or_twin_collection.

Para uma relação da esquerda para a direita , use a sintaxe a seguir.

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

Para uma relação da direita para a esquerda , use a sintaxe a seguir.

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

Para uma relação não direcional , use a sintaxe a seguir. Isso não especificará uma direção para o relacionamento, portanto, relacionamentos de qualquer direção serão incluídos no resultado.

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

Exemplos

O primeiro exemplo mostra uma travessia direcional da esquerda para a direita. Esta consulta encontra gémeos Quarto e Fábrica onde...

• Sala de alvos Factory (com qualquer nome de relacionamento)
• O quarto tem um valor de temperatura superior a 50
• Fábrica tem um $dtId de 'ABC'

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

O exemplo a seguir mostra uma travessia direcional da direita para a esquerda. Esta consulta é semelhante à anterior, mas a direção da relação entre Sala e Fábrica é invertida. Esta consulta encontra gémeos Quarto e Fábrica onde...

• Sala de alvos de fábrica (com qualquer nome de relacionamento)
• Fábrica tem um $dtId de 'ABC'
• O quarto tem um valor de temperatura superior a 50

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

O exemplo a seguir mostra uma travessia não direcional. Esta consulta encontra gémeos Quarto e Fábrica onde...

• Sala e Fábrica compartilham qualquer nome de relacionamento, indo em qualquer direção
• Fábrica tem um $dtId de 'ABC'
• O quarto tem um valor de humidade superior a 70

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

Especificar nome da relação

Opcionalmente, você pode usar a condição de relacionamento na MATCH cláusula para especificar nomes para as relações entre os gêmeos. Você pode especificar um único nome ou uma lista de nomes possíveis. O nome de relacionamento opcional é incluído como parte da sintaxe de seta para especificar a direção do relacionamento.

Se você não fornecer um nome de relacionamento, a consulta incluirá todos os nomes de relacionamento por padrão.

Sintaxe

Especifique o nome de uma relação a ser transversal na MATCH cláusula entre colchetes ([]), após dois pontos (:). Esta seção mostra a sintaxe da especificação de relações nomeadas.

Para um único nome, use a sintaxe a seguir. Os valores de espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, relationship_namee twin_or_twin_collection_2.

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

Para vários nomes possíveis, use a sintaxe a seguir. Os valores de espaço reservado que devem ser substituídos por seus valores são twin_or_twin_collection_1, relationship_name_option_1, relationship_name_option_2, twin_or_twin_collection_2e a nota para continuar o padrão conforme necessário para o número de nomes de relacionamento que você deseja inserir.

-- 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 ...

(Padrão) Para deixar o nome não especificado, deixe os colchetes vazios de informações de nome, desta forma:

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

Exemplos

O exemplo a seguir mostra um único nome de relacionamento. Esta consulta encontra gémeos Edifício e Sensor onde...

• O edifício tem uma relação "contém" com o Sensor (indo em qualquer direção)
• Edifício tem um $dtId de 'Seattle21'

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

O exemplo a seguir mostra vários nomes de relacionamento possíveis. Esta consulta é semelhante à anterior, mas há vários nomes de relacionamento possíveis que são incluídos no resultado. Esta consulta encontra gémeos Edifício e Sensor onde...

• O edifício tem uma relação 'contém' ou 'isAssociatedWith' com o Sensor (indo em qualquer direção)
• Edifício tem um $dtId de 'Seattle21'

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

O exemplo a seguir não tem um nome de relacionamento especificado. Como resultado, as relações com qualquer nome serão incluídas no resultado da consulta. Esta consulta encontra gémeos Edifício e Sensor onde...

• Building tem uma relação com o Sensor com qualquer nome (e indo em qualquer direção)
• Edifício tem um $dtId de 'Seattle21'

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

Especificar o número de lúpulos

Opcionalmente, você pode usar a condição de relacionamento na MATCH cláusula para especificar o número de saltos para as relações entre os gêmeos. Você pode especificar um número exato ou um intervalo. Esse valor opcional é incluído como parte da sintaxe de seta para especificar a direção da relação.

Se você não fornecer um número de saltos, a consulta será padronizada para um salto.

Sintaxe

Especifique o número de lúpulos a percorrer na MATCH cláusula entre parênteses retos ([]).

Para especificar um número exato de saltos, use a sintaxe a seguir. Os valores de espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, number_of_hopse twin_or_twin_collection_2.

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

Para especificar um intervalo de lúpulos, use a sintaxe a seguir. Os valores de espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, starting_limitending_limit e twin_or_twin_collection_2. O limite inicial não está incluído no intervalo, enquanto o limite final está incluído.

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

Você também pode deixar de fora o limite inicial para indicar "qualquer coisa até" (e incluindo) o limite final. Deve ser sempre previsto um limite final.

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

(Padrão) Para usar como padrão um salto, deixe os colchetes vazios de informações de salto, da seguinte forma:

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

Exemplos

O exemplo a seguir especifica um número exato de lúpulos. A consulta só retornará relações entre gêmeos Floor e Room que são exatamente 3 saltos.

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

O exemplo a seguir especifica um intervalo de lúpulos. A consulta retornará relações entre gêmeos Floor e Room que estão entre 1 e 3 saltos (o que significa que o número de saltos é 2 ou 3).

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

Você também pode mostrar um intervalo fornecendo apenas um limite. No exemplo a seguir, a consulta retornará relações entre gêmeos Floor e Room que são, no máximo, 2 saltos (o que significa que o número de saltos é 1 ou 2).

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

O exemplo a seguir não tem um número especificado de saltos, portanto, o padrão será um salto entre os gêmeos Floor e Room.

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

Atribuir variável de consulta ao relacionamento (e especificar propriedades de relacionamento)

Opcionalmente, você pode atribuir uma variável de consulta à relação referenciada na cláusula, para MATCH que possa fazer referência a ela pelo nome no texto da consulta.

Um resultado útil de fazer isso é a capacidade de filtrar as propriedades de relacionamento em sua WHERE cláusula.

Sintaxe

Para atribuir uma variável de consulta à relação, coloque o nome da variável entre colchetes ([]). Os valores de espaço reservado mostrados abaixo que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, relationship_variablee twin_or_twin_collection_2.

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

Exemplos

O exemplo a seguir atribui uma variável de consulta 'Rel' à relação. Mais tarde, na WHERE cláusula, ele usa a variável para especificar que a relação Rel deve ter uma propriedade name com um valor de 'filho'.

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

Combinar operações MATCH

Você pode combinar várias condições de relacionamento na mesma consulta. Você também pode encadear várias condições de relacionamento para expressar relações bidirecionais ou outras combinações maiores.

Sintaxe

Em uma única consulta, você pode combinar a direção do relacionamento, o nome do relacionamento e um dos números de saltos ou uma atribuição de variável de consulta.

Os exemplos de sintaxe a seguir mostram como esses atributos podem ser combinados. Você também pode deixar de fora qualquer um dos detalhes opcionais mostrados nos espaços reservados para omitir essa parte da condição.

Para especificar a direção da relação, o nome da relação e o número de saltos em uma única consulta, use a sintaxe a seguir dentro da condição de relacionamento. Os valores de espaço reservado que devem ser substituídos pelos seus valores são e , e optional_right_angle_bracket, e , relationship_name(s)e number_of_hops. optional_left_angle_bracket twin_or_twin_collection_2twin_or_twin_collection_1

-- 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 a direção do relacionamento, o nome do relacionamento e uma variável de consulta para o relacionamento em uma única consulta, use a sintaxe a seguir dentro da condição de relacionamento. Os valores de espaço reservado que devem ser substituídos pelos seus valores são e , e optional_right_angle_bracket, e , relationship_variablee relationship_name(s). optional_left_angle_bracket twin_or_twin_collection_2twin_or_twin_collection_1

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

Você pode encadear várias condições de relacionamento juntas, como esta. Os valores de espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, todas as instâncias de relationship_condition, e 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'

Exemplos

Aqui está um exemplo que combina a direção do relacionamento, o nome do relacionamento e o número de saltos. A consulta a seguir localiza os gêmeos Andar e Quarto onde a relação entre Piso e Quarto atende a estas condições:

• a relação é da esquerda para a direita, com Floor como fonte e Room como alvo
• a relação tem um nome de 'contém' ou 'isAssociatedWith'
• a relação tem 4 ou 5 lúpulos

A consulta também especifica que o piso duplo tem um $dtId de 'termostato-15'.

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

Veja um exemplo que combina a direção do relacionamento, o nome do relacionamento e uma variável de consulta nomeada para o relacionamento. A consulta a seguir localiza os gêmeos Andar e Quarto onde a relação entre Andar e Sala é atribuída a uma variável r de consulta e atende a estas condições:

• a relação é da esquerda para a direita, com Floor como fonte e Room como alvo
• a relação tem um nome de 'contém' ou 'isAssociatedWith'
• A relação, à qual é dada uma variável rde consulta, tem uma propriedade length igual a 10

A consulta também especifica que o piso duplo tem um $dtId de 'termostato-15'.

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

O exemplo a seguir ilustra condições de relacionamento encadeado . A consulta encontra gêmeos Andar, Café e Quarto, onde...

• a relação entre Piso e Sala satisfaz estas condições:
  • a relação é da esquerda para a direita, com Floor como fonte e Cafe como alvo
  • a relação tem um nome de 'contém' ou 'isAssociatedWith'
  • A relação, que é dada variável rde consulta , tem uma propriedade length igual a 10
• a relação entre Café e Quarto satisfaz as seguintes condições:
  • a relação é da direita para a esquerda, com Room como fonte e Cafe como alvo
  • a relação tem um nome de «tem» ou «inclui»
  • a relação tem até 3 (portanto 1, 2 ou 3) lúpulos

A consulta também especifica que o twin Floor tem um $dtId de 'termostato-15' e o twin Cafe tem uma 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

Você também pode usar condições de relacionamento encadeadas para expressar relações bidirecionais. A consulta a seguir encontra gêmeos Andar, Quarto e Edifício, onde...

• a relação entre Edifício e Pavimento satisfaz as seguintes condições:
  • a relação é da esquerda para a direita, com Building como fonte e Floor como alvo
  • a relação tem um nome de 'isAssociatedWith'
  • A relação recebe uma variável de consulta r1
• a relação entre Piso e Sala satisfaz estas condições:
  • a relação é da direita para a esquerda, com Room como fonte e Floor como alvo
  • a relação tem um nome de 'isAssociatedWith'
  • A relação recebe uma variável de consulta r2

A consulta também especifica que o edifício twin tem um $dtId de 'edifício-3' e o quarto tem uma 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

Limitações

Os seguintes limites aplicam-se a consultas que utilizem MATCH:

• Apenas uma MATCH expressão é suportada por instrução de consulta.

• $dtId é obrigatório na WHERE cláusula.

• A atribuição de uma variável de consulta à relação só é suportada quando a consulta especifica um único salto.

• O máximo de saltos suportados em uma consulta é 10.

• As consultas MATCH que contêm $dtId filtros em qualquer gêmeo diferente do gêmeo inicial para a travessia MATCH podem mostrar resultados vazios. Por exemplo, a seguinte consulta está sujeita a esta limitação:

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

  Se o seu cenário exigir que você use $dtId em outros gêmeos, considere usar a cláusula JOIN.

• As consultas MATCH que atravessam o mesmo gémeo várias vezes podem remover inesperadamente este gémeo dos resultados.