Поделиться через

Справочник по языку запросов Azure Digital Twins: предложение MATCH

  • Статья

В этом документе содержатся справочные сведения о предложении MATCH для языка запросов Azure Digital Twins.

Предложение MATCH используется на языке запросов Azure Digital Twins в рамках предложения FROM. MATCH позволяет указать, какой шаблон следует следовать при обходе связей в графе Azure Digital Twins (это также называется шаблоном запроса переменной прыжка).

Это предложение является необязательным для запроса.

Основной синтаксис: MATCH

MATCH поддерживает любой запрос, который находит путь между двойниками в диапазоне прыжков на основе определенных условий связи.

Условие связи может включать одно или несколько следующих сведений:

  • Направление связи (слева направо, справа налево или ненаправленное)
  • имя связи (одно имя или список возможностей)
  • Число прыжков от одного двойника к другому (точное число или диапазон)
  • Назначение переменной запроса, представляющее связь в тексте запроса. Это также позволит фильтровать свойства связи.

Запрос с MATCH предложением также должен использовать предложение WHERE, чтобы указать $dtId по крайней мере один из двойников, на которые он ссылается.

Примечание.

MATCH — это супермножество всех JOIN запросов, которые могут выполняться в хранилище запросов.

Синтаксис

Ниже приведен базовый MATCH синтаксис.

Он содержит следующие заполнители:

  • twin_or_twin_collection (x2): Предложение MATCH требует одного операнда для представления одного двойника. Другой операнд может представлять еще один двойник или коллекцию двойников.
  • relationship_condition: в этом пространстве определите условие, описывающее связь между коллекциями двойников или двойников. Условие может указать направление связи, указать имя связи, указать количество прыжков, указать свойства связи или любое сочетание этих параметров.
  • twin_ID: здесь укажите $dtId в одной из коллекций двойников, чтобы один из операндов представлял собой один двойник.
--SELECT ... FROM ...  
MATCH (twin_or_twin_collection_1)-[relationship_condition]-(twin_or_twin_collection_2)
WHERE twin_or_twin_collection.$dtId = 'twin_ID' 
-- AND ...

Вы можете оставить одну из коллекций двойников пустыми, чтобы разрешить любому двойнику работать в этом месте.

Вы также можете изменить количество условий связи, чтобы иметь несколько условий связи в цепочке или нет условий связи вообще:

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

Дополнительные сведения о каждом типе условия связи и их сочетании см. в других разделах этого документа.

Пример

Ниже приведен пример запроса с помощью MATCH.

Запрос задает направление связи и ищет двойники здания и датчика, где...

  • Датчик предназначен для любой связи со строительным двойником со $dtId зданием 21 и
  • Датчик имеет температуру выше 50. Сборка и датчик включаются в результат запроса.
SELECT Building, Sensor FROM DIGITALTWINS 
MATCH (Building)-[]->(Sensor) 
WHERE Building.$dtId = 'Building21' AND Sensor.temperature > 50

Указание направления отношений

Используйте условие связи в MATCH предложении, чтобы указать направление связи между двойниками. Возможные направления: слева направо, справа налево или ненаправленные. Циклические связи автоматически обнаруживаются, поэтому связь проходит только один раз.

Примечание.

Можно представить двунаправленные связи с помощью цепочек.

Синтаксис

Примечание.

Примеры в этом разделе посвящены направлению отношений. Они не указывают имена связей, по умолчанию они выполняют одно прыжки, и они не назначают переменные запроса отношениям. Инструкции по использованию других условий см. в разделе "Указание имени связи", "Указание количества прыжков" и "Назначение переменной запроса для связи". Сведения об использовании нескольких из них вместе в одном запросе см. в разделе "Объединение операций MATCH".

Описания связей направления используют визуальное изображение стрелки, чтобы указать направление связи. Стрелка включает пространство, отложенное квадратными скобками ([]) для необязательного имени связи.

В этом разделе показан синтаксис различных направлений связей. Значения заполнителей, которые должны быть заменены вашими значениями, и source_twin_or_twin_collection target_twin_or_twin_collection.

Для связи слева направо используйте следующий синтаксис.

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

Для связи справа налево используйте следующий синтаксис.

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

Для ненаправленной связи используйте следующий синтаксис. Это не будет указывать направление для связи, поэтому связи любого направления будут включены в результат.

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

Совет

Ненаправленные запросы требуют дополнительной обработки, что может привести к увеличению задержки и затрат.

Примеры

В первом примере показан обход слева направо. В этом запросе находятся двойники комнаты и фабрики, где...

  • Фабрика целевых объектов комнат (с любым именем связи)
  • Номер имеет значение температуры, превышающее 50
  • Фабрика имеет ABC $dtId
SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)-[]->(Factory) 
WHERE Room.temperature > 50 AND Factory.$dtId = 'ABC'

Примечание.

Запросы MATCH, содержащие $dtId фильтры для любого двойника, отличного от начального двойника для обхода MATCH, могут отображать пустые результаты. Это относится к приведенному выше примеру factory.$dtId . Дополнительные сведения см. в статье Ограничения.

В следующем примере показан обход справа налево. Этот запрос выглядит примерно так, как показано выше, но направление связи между комнатой и фабрикой обратно. В этом запросе находятся двойники комнаты и фабрики, где...

  • Фабрика целевых помещений (с любым именем связи)
  • Фабрика имеет ABC $dtId
  • Номер имеет значение температуры, превышающее 50
SELECT Room, Factory FROM DIGITALTWINS MATCH (Room)<-[]-(Factory) 
WHERE Factory.$dtId = 'ABC' AND Room.temperature > 50

В следующем примере показан ненаправленный обход. В этом запросе находятся двойники комнаты и фабрики, где...

  • Комната и фабрика разделяют любое имя отношений, идти в любом направлении
  • Фабрика имеет ABC $dtId
  • Номер имеет значение влажности, которое больше 70
SELECT Factory, Room FROM DIGITALTWINS MATCH (Factory)-[]-(Room) 
WHERE Factory.$dtId ='ABC'  AND Room.humidity > 70

Указание имени связи

При необходимости можно использовать условие связи в MATCH предложении, чтобы указать имена связей между двойниками. Можно указать одно имя или список возможных имен. Необязательное имя связи включается в синтаксис со стрелками для указания направления отношений.

Если имя связи не указано, запрос будет содержать все имена связей по умолчанию.

Совет

Указание имен связей в запросе может повысить производительность и сделать результаты более предсказуемыми.

Синтаксис

Примечание.

В примерах этого раздела основное внимание уделяется имени связи. Все они показывают ненаправленные связи, по умолчанию они по умолчанию выполняют один прыжк, и они не назначают переменные запроса отношениям. Инструкции по использованию других условий см. в разделе "Указание направления отношений", "Указание количества прыжков" и "Назначение переменной запроса для связи". Сведения об использовании нескольких из них вместе в одном запросе см. в разделе "Объединение операций MATCH".

Укажите имя связи для обхода в предложении в MATCH квадратных скобках ([]), после двоеточия (:). В этом разделе показан синтаксис указания именованных связей.

Для одного имени используйте следующий синтаксис. Значения заполнителей, которые должны быть заменены вашими значениями, relationship_name— twin_or_twin_collection_1и twin_or_twin_collection_2.

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

Для нескольких возможных имен используется следующий синтаксис. Значения заполнителей, которые должны быть заменены вашими значениямиtwin_or_twin_collection_1: , relationship_name_option_2relationship_name_option_1twin_or_twin_collection_2и примечание, чтобы продолжить шаблон при необходимости для количества имен связей, которые необходимо ввести.

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

Внимание

Двоеточие (:) в квадратных скобках является обязательной частью синтаксиса для указания имени связи в запросе MATCH . Если вы не включаете двоеточие, запрос не указывает имя связи. Вместо этого у вас есть запрос, который назначает переменную запроса связи.

(по умолчанию) Чтобы оставить имя не указано, оставьте квадратные скобки пустыми сведениями об имени, как показано ниже:

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

Примеры

В следующем примере показано одно имя связи. Этот запрос находит двойники здания и датчика, где...

  • Здание имеет отношение "содержит" к датчику (идет в любом направлении)
  • Здание имеет $dtId "Сиэтл21"
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

В следующем примере показаны несколько возможных имен связей. Этот запрос выглядит примерно так, как показано выше, но есть несколько возможных имен связей, включенных в результат. Этот запрос находит двойники здания и датчика, где...

  • Сборка имеет отношение "содержит" или "isAssociatedWith" к датчику (идет в любом направлении)
  • Здание имеет $dtId "Сиэтл21"
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building)-[:contains|isAssociatedWith]-(Sensor)  
WHERE building.$dtId = 'Seattle21'

В следующем примере нет указанного имени связи. В результате связи с любым именем будут включены в результат запроса. Этот запрос находит двойники здания и датчика, где...

  • Построение имеет отношение к датчику с любым именем (и идет в любом направлении)
  • Здание имеет $dtId "Сиэтл21"
SELECT Building, Sensor FROM DIGITALTWINS   
MATCH (Building-[]-(Sensor)  
WHERE Building.$dtId = 'Seattle21'

Укажите количество прыжков

При необходимости можно использовать условие связи в MATCH предложении, чтобы указать количество прыжков для связей между двойниками. Можно указать точное число или диапазон. Это необязательное значение включается в синтаксис со стрелками для указания направления связи.

Если вы не предоставляете несколько прыжков, запрос по умолчанию будет использоваться одним прыжком.

Внимание

Если указать количество прыжков, превышающее одно, вы не можете назначить переменную запроса связи. В одном запросе можно использовать только одно из этих условий.

Синтаксис

Примечание.

Примеры в этом разделе посвящены количеству прыжков. Все они показывают ненаправленные связи без указания имен. Инструкции по использованию других условий см. в разделе "Указание направления отношений" и "Указание имени связи". Сведения об использовании нескольких из них вместе в одном запросе см. в разделе "Объединение операций MATCH".

Укажите количество прыжков для обхода в предложении в MATCH квадратных скобках ([]).

Чтобы указать точное количество прыжков, используйте следующий синтаксис. Значения заполнителей, которые должны быть заменены вашими значениями, number_of_hops— twin_or_twin_collection_1и twin_or_twin_collection_2.

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

Чтобы указать диапазон прыжков, используйте следующий синтаксис. Значения заполнителей, которые должны быть заменены вашими значениями, starting_limitending_limit — twin_or_twin_collection_1и twin_or_twin_collection_2. Начальный предел не включен в диапазон, а конечный предел включен.

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

Вы также можете выйти из начального предела, чтобы указать "что-либо до" (и в том числе) конечного предела. Конечное ограничение всегда должно быть предоставлено.

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

(по умолчанию) Чтобы по умолчанию использовать один прыжок, оставьте квадратные скобки пустыми сведениями о прыжке, как показано ниже:

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

Примеры

В следующем примере указывается точное количество прыжков. Запрос возвращает только связи между двойниками и комнатой, которые ровно 3 прыжка.

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

В следующем примере указывается диапазон прыжков. Запрос вернет связи между двойниками и комнатой, которые находятся в диапазоне от 1 до 3 прыжков (то есть количество прыжков равно 2 или 3).

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

Кроме того, можно отобразить диапазон, предоставив только одну границу. В следующем примере запрос вернет связи между двойниками Floor и Room, которые находятся не более 2 прыжков (то есть количество прыжков равно 1 или 2).

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

В следующем примере нет указанного количества прыжков, поэтому по умолчанию используется один прыжок между двойниками и комнатой.

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

Назначение переменной запроса для связи (и указание свойств связи)

При необходимости можно назначить переменную запроса связи, на которую MATCH ссылается предложение, чтобы можно было ссылаться на нее по имени в тексте запроса.

Полезным результатом этого является возможность фильтрации свойств связей в предложении WHERE .

Внимание

Назначение переменной запроса связи поддерживается только в том случае, если запрос задает один прыжк. В запросе необходимо выбрать между указанием переменной связи и указанием большего количества прыжков.

Синтаксис

Примечание.

В примерах этого раздела основное внимание уделяется переменной запроса для связи. Все они показывают ненаправленные связи без указания имен. Инструкции по использованию других условий см. в разделе "Указание направления отношений" и "Указание имени связи". Сведения об использовании нескольких из них вместе в одном запросе см. в разделе "Объединение операций MATCH".

Чтобы назначить переменную запроса связи, поместите имя переменной в квадратные скобки ([]). Значения заполнителей, показанные ниже, которые должны быть заменены вашими значениями twin_or_twin_collection_1: , relationship_variableи twin_or_twin_collection_2.

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

Примеры

В следующем примере для связи назначается переменная запроса "Rel". Позже в WHERE предложении используется переменная, чтобы указать, что отношение Rel должно иметь свойство name со значением child.

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

Объединение операций MATCH

В одном запросе можно объединить несколько условий связи. Можно также связать несколько условий связи для выражения двунаправленных связей или других более крупных сочетаний.

Синтаксис

В одном запросе можно объединить направление связи, имя связи и одно из нескольких прыжков или назначение переменной запроса.

В следующих примерах синтаксиса показано, как можно объединить эти атрибуты. Вы также можете исключить любую из необязательных сведений, отображаемых в заполнителях, чтобы опустить эту часть условия.

Чтобы указать направление связи, имя связи и количество прыжков в одном запросе, используйте следующий синтаксис в условии связи. Значения заполнителей, которые должны быть заменены вашими значениямиtwin_or_twin_collection_1, и twin_or_twin_collection_2, optional_left_angle_bracket а также , relationship_name(s)а optional_right_angle_bracketтакже 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

Чтобы указать направление связи, имя связи и переменную запроса для связи в одном запросе, используйте следующий синтаксис в условии связи. Значения заполнителей, которые должны быть заменены вашими значениямиtwin_or_twin_collection_1, и twin_or_twin_collection_2, optional_left_angle_bracket а также , relationship_variableа optional_right_angle_bracketтакже 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

Примечание.

В зависимости от параметров указания направления связи необходимо выбрать между левой угловой скобкой для связи слева направо или правой угловой скобкой для связи справа налево. Вы не можете включить оба на одну стрелку, но может представлять двунаправленные связи путем цепочки.

Вы можете объединить несколько условий связи, как показано ниже. Значения заполнителей, которые должны быть заменены вашими значениями twin_or_twin_collection_1: все экземпляры relationship_conditionи 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'

Примеры

Ниже приведен пример, который объединяет направление отношений, имя связи и количество прыжков. Следующий запрос находит двойников Floor и Room, где связь между Полом и комнатой соответствует следующим условиям:

  • отношение слева направо, с Полом в качестве источника и комнаты в качестве целевого объекта
  • Отношение имеет имя "contains" или "isAssociatedWith"
  • Отношение имеет либо 4, либо 5 прыжков

Запрос также указывает, что twin Floor имеет $dtId тип "термостат-15".

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

Ниже приведен пример, который объединяет направление связи, имя связи и именованную переменную запроса для связи. Следующий запрос находит двойников Floor и Room, где связь между Полом и Комнатой назначается переменной r запроса и соответствует следующим условиям:

  • отношение слева направо, с Полом в качестве источника и комнаты в качестве целевого объекта
  • Отношение имеет имя "contains" или "isAssociatedWith"
  • Отношение, заданное переменной rзапроса, имеет свойство длины, равное 10

Запрос также указывает, что twin Floor имеет $dtId тип "термостат-15".

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

В следующем примере показаны условия связи с цепочкой . Запрос находит двойников пол, кафе и комнату, где...

  • Связь между полом и комнатой соответствует следующим условиям:
    • отношения слева направо, с Полом в качестве источника и кафе в качестве цели
    • Отношение имеет имя "contains" или "isAssociatedWith"
    • Отношение, заданное переменной rзапроса, имеет свойство длины, равное 10
  • Отношения между кафе и комнатой соответствуют следующим условиям:
    • отношения справа налево, с Комнатой в качестве источника и кафе в качестве цели
    • Отношение имеет имя "has" или "includes"
    • Отношение имеет до 3 (поэтому 1, 2 или 3) прыжки

Запрос также указывает, что двойник Floor имеет "термостат-15" и twin Cafe имеет $dtId температуру 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

Для выражения двунаправленных связей можно также использовать условия связи с цепочкой. Следующий запрос находит двойников Floor, Room и Building, где...

  • Связь между зданием и этажом соответствует следующим условиям:
    • связь слева направо, с зданием в качестве источника и пола в качестве целевого объекта
    • Связь имеет имя isAssociatedWith
    • Связь получает переменную запроса r1
  • Связь между полом и комнатой соответствует следующим условиям:
    • отношение справа налево, с комнатой в качестве источника и пола в качестве целевого объекта
    • Связь имеет имя isAssociatedWith
    • Связь получает переменную запроса r2

Запрос также указывает, что здание двойника имеет $dtId "здание-3", а комната имеет температуру более 50.

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

Ограничения

Следующие ограничения применяются к запросам с помощью MATCH:

  • Для каждой инструкции запроса поддерживается только одно MATCH выражение.

  • $dtId требуется в предложении WHERE .

  • Назначение переменной запроса связи поддерживается только в том случае, если запрос задает один прыжк.

  • Максимальное число прыжков, поддерживаемых в запросе, равно 10.

  • Запросы MATCH, содержащие $dtId фильтры для любого двойника, отличного от начального двойника для обхода MATCH, могут отображать пустые результаты. Например, следующий запрос подлежит этому ограничению:

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

    Если для сценария требуется использовать другие двойники, рекомендуется использовать $dtId предложение JOIN .

  • Запросы MATCH, которые проходят через один и тот же двойник несколько раз, могут неожиданно удалить этот двойник из результатов.