Compartilhar via

Referência da linguagem de consulta de Gêmeos Digitais do Azure: cláusula MATCH

  • Artigo

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

A cláusula MATCH é usada na linguagem de consulta dos Gêmeos Digitais do Azure como parte da cláusula FROM. MATCH permite que você especifique qual padrão deve ser seguido ao percorrer relações no grafo Gêmeos Digitais do Azure (isso também é conhecido como um padrão de consulta de "salto variável").

Essa cláusula é opcional durante a consulta.

Sintaxe principal: MATCH

MATCH dá suporte a consultas que encontrem um caminho entre os gêmeos dentro de um intervalo de saltos, com base em determinadas condições de relações.

A condição de relação pode incluir um ou mais destes detalhes:

Uma consulta com uma cláusula MATCH também precisa usar a cláusula WHERE para especificar o $dtId para pelo menos um dos gêmeos referenciados.

Observação

MATCH é um superconjunto JOIN de todas as consultas que podem ser executadas no armazenamento de consultas.

Sintaxe

Esta é a sintaxe MATCH básica.

Ele contém estes espaços reservados:

--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ê poderá deixar uma das coleções de gêmeos em branco para permitir que qualquer gêmeo trabalhe naquele local.

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

--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 relação e como combiná-las, consulte as outras seções deste documento.

Exemplo

Veja um exemplo de consulta usando MATCH.

A consulta especifica uma direção de relação e pesquisa por gêmeos de Building e Sensor em que...

  • o Sensor é o destino de qualquer relação de um gêmeo Building com um $dtId de Building21 e
  • o Sensor tem uma temperatura acima de 50. O Prédio 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 da relação

Use a condição de relação na MATCH cláusula para especificar uma direção de relação 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 detectadas automaticamente, de modo que uma relação seja percorrida apenas uma vez.

Observação

É possível representar relações bidirecionais usando encadeamento.

Sintaxe

Observação

Os exemplos nesta seção se concentram na direção da relação. Eles não especificam nomes de relação, assumem como padrão um único salto e não atribuem variáveis de consulta às relações. Para ver instruções sobre como fazer mais com essas outras condições, consulte Especificar nome da relação, Especificar número de saltos e Atribuir variável de consulta à relação. Para obter informações sobre como usar vários deles juntos na mesma consulta, consulte Combinar operações MATCH.

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

Esta seção mostra a sintaxe para diferentes direções de relações. Os valores do 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 seguinte sintaxe.

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

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

Para uma relação não direcional, use a seguinte sintaxe. Isso não especificará uma direção para a relação, portanto, as relações de qualquer direção serão incluídas no resultado.

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

Dica

Consultas não direcionais exigem processamento adicional, o que pode resultar em maior latência e custo.

Exemplos

O primeiro exemplo mostra uma traversal direcional da esquerda para a direita. Esta consulta encontra os gêmeos Room e Factory em que...

  • Room é destinado a Factory (com qualquer nome de relação)
  • Room tem um valor de temperatura maior que 50
  • Factory tem um $dtId de 'ABC'
SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)-[]->(Factory) 
WHERE Room.temperature > 50 AND Factory.$dtId = 'ABC'

Observação

As consultas MATCH que contêm filtros $dtId em um gêmeo diferente do gêmeo inicial para a travessia MATCH podem mostrar resultados vazios. Isso se aplica ao factory.$dtId no exemplo acima. Para obter mais informações, confira Limitações.

O seguinte exemplo mostra uma traversal direcional da direita para a esquerda. Esta consulta é similar à consulta acima, mas a direção da relação entre Room e Factory é inversa. Esta consulta encontra os gêmeos Room e Factory em que...

  • Factory é destinado a Room (com qualquer nome de relação)
  • Factory tem um $dtId de 'ABC'
  • Room tem um valor de temperatura maior que 50
SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)<-[]-(Factory) 
WHERE Factory.$dtId = 'ABC' AND Room.temperature > 50

O seguinte exemplo mostra uma traversal não direcional. Esta consulta encontra os gêmeos Room e Factory em que...

  • Room e Factory compartilham qualquer nome de relação em qualquer direção
  • Factory tem um $dtId de 'ABC'
  • Room tem um valor de umidade maior que 70
SELECT Factory, Room FROM DIGITALTWINS MATCH (Factory)-[]-(Room) 
WHERE Factory.$dtId ='ABC'  AND Room.humidity > 70

Especificar o nome da relação

Opcionalmente, você pode usar a condição de relação na cláusula MATCH 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 da relação opcional é incluído como parte da sintaxe de seta para especificar a direção da relação.

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

Dica

Especificar nomes de relação na consulta pode melhorar o desempenho e tornar os resultados mais previsíveis.

Sintaxe

Observação

Os exemplos nesta seção se concentram no nome da relação. Todos eles mostram relações não direcionais, assumem como padrão um único salto e não atribuem variáveis de consulta às relações. Para ver instruções sobre como fazer mais com essas outras condições, consulte Especificar direção da relação, Especificar número de saltos e Atribuir variável de consulta à relação. Para obter informações sobre como usar vários deles juntos na mesma consulta, consulte Combinar operações MATCH.

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

Para um nome único, use a seguinte sintaxe. Os valores do espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, relationship_name e 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 pelos valores são twin_or_twin_collection_1, relationship_name_option_1, relationship_name_option_2, twin_or_twin_collection_2 e a observação para continuar o padrão conforme necessário para o número de nomes de relação 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 ...

Importante

Os dois pontos (:) entre colchetes são uma parte necessária da sintaxe para especificar um nome de relacionamento em uma consulta MATCH. Se você não incluir os dois pontos, sua consulta não especificará um nome de relacionamento. Em vez disso, você tem uma consulta que atribui uma variável de consulta à relação.

(Padrão) Para deixar o nome sem especificação, deixe os colchetes em branco, sem qualquer informação de nome, por exemplo:

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

Exemplos

O exemplo a seguir mostra uma única relação de nome. Esta consulta encontra os gêmeos Building e Sensor em que...

  • Building tem uma relação 'contains' com Sensor (em qualquer direção)
  • Building tem $dtId igual a 'Seattle21'
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

O exemplo a seguir mostra vários nomes de relação possíveis. Essa consulta é semelhante à acima, mas há vários nomes de relação possíveis incluídos no resultado. Esta consulta encontra os gêmeos Building e Sensor em que...

  • Building tem uma relação 'contains' ou 'isAssociatedWith' com Sensor (em qualquer direção)
  • Building tem $dtId igual a 'Seattle21'
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains|isAssociatedWith]-(Sensor)  
WHERE building.$dtId = 'Seattle21'

O exemplo a seguir não tem nenhum nome de relação especificado. Como resultado, as relações com qualquer nome serão incluídas no resultado da consulta. Esta consulta encontra os gêmeos Building e Sensor em que...

  • Building tem uma relação com Sensor com qualquer nome (e em qualquer direção)
  • Building tem $dtId igual a 'Seattle21'
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building-[]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

Especificar o número de saltos

Opcionalmente, você pode usar a condição de relação na cláusula MATCH 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á padrão para um salto.

Importante

Se você especificar um número de saltos maior que um, não poderá atribuir uma variável de consulta à relação. Somente uma dessas condições pode ser usada dentro da mesma consulta.

Sintaxe

Observação

Os exemplos nesta seção se concentram no número de saltos. Todos eles mostram relações não direcionais sem especificar nomes. Para ver instruções sobre como fazer mais com essas outras condições, consulte Especificar direção da relação e Especificar nome da relação. Para obter informações sobre como usar vários deles juntos na mesma consulta, consulte Combinar operações MATCH.

Especifique o número de saltos a percorrer na cláusula MATCH dentro dos colchetes ([]).

Para especificar um número exato de saltos, use a seguinte sintaxe. Os valores do espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, number_of_hops e 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 saltos, use a seguinte sintaxe. Os valores de espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, starting_limit, ending_limit e twin_or_twin_collection_2. O limite inicial não é incluído no intervalo, já o limite final é 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. Um limite final sempre deve ser fornecido.

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

(Padrão) Para usar o padrão de um salto, deixe os colchetes sem qualquer informação de salto, por exemplo:

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

Exemplos

O seguinte exemplo especifica um número exato de saltos. A consulta só retornará as relações entre os gêmeos Floor e Room que têm exatamente três saltos.

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

O exemplo a seguir especifica um intervalo de saltos. A consulta retornará relações entre os gêmeos Floor e Room que têm entre um e três saltos (o que significa que o número de saltos será dois ou três).

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. Neste exemplo, a consulta retornará as relações entre os gêmeos Floor e Room que têm no máximo dois saltos (o que significa que o número de saltos será um ou dois).

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

O seguinte exemplo não tem um número específico de saltos, assim o padrão será de 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 à relação (e especificar propriedades de relação)

Opcionalmente, você pode atribuir uma variável de consulta à relação referenciada na cláusula MATCH, para que você 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 relação em sua cláusula WHERE.

Importante

A atribuição de uma variável de consulta à relação só tem suporte quando a consulta especifica um único salto. Em uma consulta, você deve escolher entre especificar uma variável de relação e especificar um número maior de saltos.

Sintaxe

Observação

Os exemplos nesta seção se concentram em uma variável de consulta para a relação. Todos eles mostram relações não direcionais sem especificar nomes. Para ver instruções sobre como fazer mais com essas outras condições, consulte Especificar direção da relação e Especificar nome da relação. Para obter informações sobre como usar vários deles juntos na mesma consulta, consulte Combinar operações MATCH.

Para atribuir uma variável de consulta à relação, coloque o nome da variável entre colchetes ([]). Os valores do espaço reservado mostrados abaixo que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, relationship_variable e 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 cláusula WHERE, isso usa a variável para especificar que a relação Rel deve ter um nome de propriedade com o valor 'child'.

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 relação na mesma consulta. Você também pode encadear várias condições de relação para expressar relações bidirecionais ou outras combinações maiores.

Sintaxe

Em uma única consulta, você pode combinar direção do relacionamento, nome do relacionamento e um dos número 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 relação. Os valores do espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1 e twin_or_twin_collection_2, optional_left_angle_bracket e optional_right_angle_bracket, relationship_name(s) e 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 a direção da relação, o nome da relação e a variável de consulta da relação em uma única consulta, use a sintaxe a seguir dentro da condição de relação. Os valores do espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1 e twin_or_twin_collection_2, optional_left_angle_bracket e optional_right_angle_bracket, relationship_variable e 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

Observação

De acordo com as opções para especificar a direção da relação, você deve escolher entre um colchete angular esquerdo para uma relação da esquerda para a direita ou um colchete angular direito para uma relação da direita para a esquerda. Você não pode incluir os dois na mesma seta, mas pode representar relações bidirecionais encadeando.

Você pode encadear muitas condições de relação juntas desta forma. Os valores do espaço reservado que devem ser substituídos pelos seus valores são twin_or_twin_collection_1, todos 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 da relação, o nome da relação e o número de saltos. A seguinte consulta encontra os gêmeos Floor e Room, em que a relação entre Floor e Room atende a estas condições:

  • a relação é da esquerda para a direita, sendo Floor a origem e Room o destino
  • a relação tem um nome de 'contains' ou 'isAssociatedWith'
  • a relação tem 4 ou 5 saltos

A consulta também especifica que o gêmeo Floor tem um $dtId de 'thermostat-15'.

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

Aqui está um exemplo que combina a direção da relação, o nome da relação e uma variável de consulta nomeada para a relação. A seguinte consulta encontra os gêmeos Floor e Room, em que a relação entre eles é atribuída a uma variável de consulta r e atende a estas condições:

  • a relação é da esquerda para a direita, sendo Floor a origem e Room o destino
  • a relação tem um nome de 'contains' ou 'isAssociatedWith'
  • a relação, que recebe uma variável de consulta r, tem uma propriedade de comprimento igual a 10

A consulta também especifica que o gêmeo Floor tem um $dtId de 'thermostat-15'.

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

O seguinte exemplo ilustra as condições de cadeia da relação. A consulta encontra os gêmeos Floor, Cafe e Room, em que...

  • a relação entre Floor e Room atende a estas condições:
    • a relação é da esquerda para a direita, sendo Floor a origem e Cafe o destino
    • a relação tem um nome de 'contains' ou 'isAssociatedWith'
    • a relação, que é dada variável de consulta r, tem uma propriedade de comprimento igual a 10
  • a relação entre Cafe e Room atende a estas condições:
    • a relação é da direita para a esquerda, sendo Room a origem e Cafe o destino
    • a relação tem um nome de 'has' ou 'includes'
    • a relação tem até 3 saltos (portanto, 1, 2 ou 3)

A consulta também especifica que o gêmeo Floor tem $dtId igual a 'thermostat-15' e o gêmeo 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 relação encadeadas para expressar relações bidirecionais. A consulta a seguir encontra os gêmeos Floor, Room e Building, em que...

  • a relação entre Building e Floor atende a estas condições:
    • a relação é da esquerda para a direita, sendo Building a origem e Floor o destino
    • a relação tem um nome 'isAssociatedWith'
    • a relação recebe uma variável de consulta r1
  • a relação entre Floor e Room atende a estas condições:
    • a relação é da direita para a esquerda, sendo Room a origem e Floor o destino
    • a relação tem um nome 'isAssociatedWith'
    • a relação recebe uma variável de consulta r2

A consulta também especifica que o gêmeo Building tem $dtId igual 'building-3' e Room tem uma temperatura maior que 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 limites a seguir se aplicam a consultas que usam MATCH:

  • Somente uma expressão MATCH é aceita por instrução de consulta.

  • $dtId é necessário na cláusula WHERE.

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

  • O número máximo de saltos com suporte em uma consulta é dez.

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

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

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

  • Consultas MATCH que atravessam o mesmo gêmeo várias vezes podem remover inesperadamente esse gêmeo dos resultados.