Skip to content

Commit ddfea95

Browse files
MikeRayMSFTMikeRayMSFT
committed
Add arbitrary length - refresh formatting.
1 parent 133abf2 commit ddfea95

File tree

1 file changed

+110
-82
lines changed

1 file changed

+110
-82
lines changed

‎docs/t-sql/queries/match-sql-graph.md

Lines changed: 110 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@ title: "MATCH (SQL Graph)"
33
description: "MATCH (Transact-SQL)"
44
author: MikeRayMSFT
55
ms.author: mikeray
6-
ms.date: "06/26/2019"
6+
ms.reviewer: randolphwest
7+
ms.date: 07/01/2025
78
ms.service: sql
89
ms.subservice: t-sql
910
ms.topic: reference
@@ -19,128 +20,137 @@ helpviewer_keywords:
1920
- "Shortest Path, shortest_path"
2021
dev_langs:
2122
- "TSQL"
23+
ai-usage: "ai-assisted"
2224
monikerRange: "=azuresqldb-current || >=sql-server-2017 || >=sql-server-linux-2017 || =azuresqldb-mi-current || =fabric"
2325
---
2426
# MATCH (Transact-SQL)
27+
2528
[!INCLUDE [sqlserver2017-asdb-asdbmi-fabricsqldb](../../includes/applies-to-version/sqlserver2017-asdb-asdbmi-fabricsqldb.md)]
2629

27-
Specifies a search condition for a graph. MATCH can be used only with graph node and edge tables, in the SELECT statement as part of WHERE clause.
28-
29-
:::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: [Transact-SQL syntax conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)
30-
31-
## Syntax
32-
30+
Specifies a search condition for a graph. MATCH can be used only with graph node and edge tables, in the SELECT statement as part of WHERE clause.
31+
32+
:::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: [Transact-SQL syntax conventions](../../t-sql/language-elements/transact-sql-syntax-conventions-transact-sql.md)
33+
34+
## Syntax
35+
3336
```syntaxsql
3437
MATCH (<graph_search_pattern>)
3538
3639
<graph_search_pattern>::=
37-
{
38-
<simple_match_pattern>
39-
| <arbitrary_length_match_pattern>
40-
| <arbitrary_length_match_last_node_predicate>
40+
{
41+
<simple_match_pattern>
42+
| <arbitrary_length_match_pattern>
43+
| <arbitrary_length_match_last_node_predicate>
4144
}
4245
4346
<simple_match_pattern>::=
4447
{
45-
LAST_NODE(<node_alias>) | <node_alias> {
46-
{ <-( <edge_alias> )- }
48+
LAST_NODE(<node_alias>) | <node_alias> {
49+
{ <-( <edge_alias> )- }
4750
| { -( <edge_alias> )-> }
4851
<node_alias> | LAST_NODE(<node_alias>)
49-
}
52+
}
5053
}
5154
[ { AND } { ( <simple_match_pattern> ) } ]
52-
[ ,...n ]
55+
[ , ...n ]
5356
5457
<node_alias> ::=
55-
node_table_name | node_table_alias
58+
node_table_name | node_table_alias
5659
5760
<edge_alias> ::=
5861
edge_table_name | edge_table_alias
5962
60-
6163
<arbitrary_length_match_pattern> ::=
62-
{
63-
SHORTEST_PATH(
64-
<arbitrary_length_pattern>
65-
[ { AND } { <arbitrary_length_pattern> } ]
66-
[ ,…n]
64+
{
65+
SHORTEST_PATH(
66+
<arbitrary_length_pattern>
67+
[ { AND } { <arbitrary_length_pattern> } ]
68+
[ , ...n ]
6769
)
68-
}
70+
}
6971
7072
<arbitrary_length_match_last_node_predicate> ::=
7173
{ LAST_NODE( <node_alias> ) = LAST_NODE( <node_alias> ) }
7274
73-
7475
<arbitrary_length_pattern> ::=
75-
{ LAST_NODE( <node_alias> ) | <node_alias>
76-
( <edge_first_al_pattern> [<edge_first_al_pattern>…,n] )
77-
<al_pattern_quantifier>
76+
{ LAST_NODE( <node_alias> ) | <node_alias>
77+
( <edge_first_al_pattern> [ <edge_first_al_pattern>... , n ] )
78+
<al_pattern_quantifier>
7879
}
79-
| ( {<node_first_al_pattern> [<node_first_al_pattern> …,n] )
80-
<al_pattern_quantifier>
81-
LAST_NODE( <node_alias> ) | <node_alias>
80+
| ( { <node_first_al_pattern> [ <node_first_al_pattern> ... , n ] )
81+
<al_pattern_quantifier>
82+
LAST_NODE( <node_alias> ) | <node_alias>
8283
}
83-
84+
8485
<edge_first_al_pattern> ::=
85-
{ (
86-
{ -( <edge_alias> )-> }
87-
| { <-( <edge_alias> )- }
86+
{ (
87+
{ -( <edge_alias> )-> }
88+
| { <-( <edge_alias> )- }
8889
<node_alias>
89-
)
90-
}
90+
)
91+
}
9192
9293
<node_first_al_pattern> ::=
93-
{ (
94-
<node_alias>
95-
{ <-( <edge_alias> )- }
94+
{ (
95+
<node_alias>
96+
{ <-( <edge_alias> )- }
9697
| { -( <edge_alias> )-> }
97-
)
98-
}
99-
98+
)
99+
}
100100
101101
<al_pattern_quantifier> ::=
102102
{
103-
+
104-
| { 1 , n }
103+
+
104+
| { 1 , n }
105105
}
106106
107107
n - positive integer only.
108-
109108
```
110109

111110
## Arguments
112-
*graph_search_pattern*
111+
112+
#### *graph_search_pattern*
113+
113114
Specifies the pattern to search or path to traverse in the graph. This pattern uses ASCII art syntax to traverse a path in the graph. The pattern goes from one node to another via an edge, in the direction of the arrow provided. Edge names or aliases are provided inside parentheses. Node names or aliases appear at the two ends of the arrow. The arrow can go in either direction in the pattern.
114115

115-
*node_alias*
116+
#### *node_alias*
117+
116118
Name or alias of a node table provided in the FROM clause.
117119

118-
*edge_alias*
120+
#### *edge_alias*
121+
119122
Name or alias of an edge table provided in the FROM clause.
120123

121-
*SHORTEST_PATH*
124+
#### *SHORTEST_PATH*
125+
122126
Shortest path function is used to find shortest path between two given nodes in a graph or between a given node and all the other nodes in a graph. It takes an arbitrary length pattern as input, that is searched repeatedly in a graph. Introduced in SQL Server 2019. Requires SQL Server 2019 or later.
123127

124-
*arbitrary_length_match_pattern*
125-
Specifies the nodes and edges that must be traversed repeatedly until the desired node is reached or until the maximum number of iterations as specified in the pattern is met.
128+
#### *arbitrary_length_match_pattern*
129+
130+
Specifies the nodes and edges that must be traversed repeatedly until the desired node is reached or until the maximum number of iterations as specified in the pattern is met.
131+
132+
#### *al_pattern_quantifier*
133+
134+
The arbitrary length pattern takes regular expression style pattern quantifiers in order to specify the number of times a given search pattern is repeated. The supported search pattern quantifiers are:
135+
136+
- **+**: Repeat the pattern 1 or more times. Terminate as soon as a shortest path is found.
137+
- **{1,n}**: Repeat the pattern 1 to *n* times. Terminate as soon as a shortest path is found.
126138

127-
*al_pattern_quantifier*
128-
The arbitrary length pattern takes regular expression style pattern quantifiers in order to specify the number of times a given search pattern is repeated. The supported search pattern quantifiers are:
129-
* **+**: Repeat the pattern 1 or more times. Terminate as soon as a shortest path is found.
130-
* **{1,n}**: Repeat the pattern 1 to *n* times. Terminate as soon as a shortest path is found.
139+
## Remarks
131140

132-
## Remarks
133-
The node names inside MATCH can be repeated. In other words, a node can be traversed an arbitrary number of times in the same query.
134-
An edge name cannot be repeated inside MATCH.
141+
The node names inside MATCH can be repeated. In other words, a node can be traversed an arbitrary number of times in the same query.
142+
An edge name can't be repeated inside MATCH.
135143
An edge can point in either direction, but it must have an explicit direction.
136-
OR and NOT operators are not supported in the MATCH pattern.
137-
MATCH can be combined with other expressions using AND in the WHERE clause. However, combining it with other expressions using OR or NOT is not supported.
144+
OR and NOT operators aren't supported in the MATCH pattern.
145+
MATCH can be combined with other expressions using AND in the WHERE clause. However, combining it with other expressions using OR or NOT isn't supported.
138146

139-
## Examples
140-
### A. Find a friend
141-
The following example creates a Person node table and friends Edge table, inserts some data and then uses MATCH to find friends of Alice, a person in the graph.
147+
## Examples
142148

143-
```sql
149+
### Find a friend
150+
151+
The following example creates a Person node table and friends Edge table, inserts some data and then uses MATCH to find friends of Alice, a person in the graph.
152+
153+
```sql
144154
-- Create person node table
145155
CREATE TABLE dbo.Person (ID INTEGER PRIMARY KEY, name VARCHAR(50)) AS NODE;
146156
CREATE TABLE dbo.friend (start_date DATE) AS EDGE;
@@ -167,48 +177,66 @@ WHERE MATCH(Person1-(friend)->Person2)
167177
AND Person1.name = 'Alice';
168178
```
169179

170-
### B. Find friend of a friend
171-
The following example tries to find friend of a friend of Alice.
180+
### Find friend of a friend
172181

173-
```sql
174-
SELECT Person3.name AS FriendName
182+
The following example tries to find friend of a friend of Alice.
183+
184+
```sql
185+
SELECT Person3.name AS FriendName
175186
FROM Person Person1, friend, Person Person2, friend friend2, Person Person3
176187
WHERE MATCH(Person1-(friend)->Person2-(friend2)->Person3)
177188
AND Person1.name = 'Alice';
178189
```
179190

180-
### C. More `MATCH` patterns
181-
Following are some more ways in which a pattern can be specified inside MATCH.
191+
### Find people 1-3 hops away from a given person
192+
193+
The following example finds the shortest path between Jacob and all the people that Jacob is connected to in the graph one to three hops away from him.
182194

183-
```sql
195+
```sql
196+
SELECT
197+
Person1.name AS PersonName,
198+
STRING_AGG(Person2.name, '->') WITHIN GROUP (GRAPH PATH) AS Friends
199+
FROM
200+
Person AS Person1,
201+
friendOf FOR PATH AS fo,
202+
Person FOR PATH AS Person2
203+
WHERE MATCH(SHORTEST_PATH(Person1(-(fo)->Person2){1,3}))
204+
AND Person1.name = 'Jacob'
205+
```
206+
207+
### More patterns
208+
209+
Following are some more ways in which a pattern can be specified inside MATCH.
210+
211+
```sql
184212
-- Find a friend
185213
SELECT Person2.name AS FriendName
186214
FROM Person Person1, friend, Person Person2
187215
WHERE MATCH(Person1-(friend)->Person2);
188-
216+
189217
-- The pattern can also be expressed as below
190218

191219
SELECT Person2.name AS FriendName
192-
FROM Person Person1, friend, Person Person2
220+
FROM Person Person1, friend, Person Person2
193221
WHERE MATCH(Person2<-(friend)-Person1);
194222

195-
196223
-- Find 2 people who are both friends with same person
197224
SELECT Person1.name AS Friend1, Person2.name AS Friend2
198-
FROM Person Person1, friend friend1, Person Person2,
225+
FROM Person Person1, friend friend1, Person Person2,
199226
friend friend2, Person Person0
200227
WHERE MATCH(Person1-(friend1)->Person0<-(friend2)-Person2);
201-
228+
202229
-- this pattern can also be expressed as below
203230

204231
SELECT Person1.name AS Friend1, Person2.name AS Friend2
205-
FROM Person Person1, friend friend1, Person Person2,
232+
FROM Person Person1, friend friend1, Person Person2,
206233
friend friend2, Person Person0
207234
WHERE MATCH(Person1-(friend1)->Person0 AND Person2-(friend2)->Person0);
208235
```
209-
210236

211-
## See Also
212-
[CREATE TABLE &#40;SQL Graph&#41;](../../t-sql/statements/create-table-sql-graph.md)
213-
[INSERT (SQL Graph)](../../t-sql/statements/insert-sql-graph.md)]
214-
[Graph processing with SQL Server 2017](../../relational-databases/graphs/sql-graph-overview.md)
237+
## Related content
238+
239+
- [CREATE TABLE (SQL Graph)](../statements/create-table-sql-graph.md)
240+
- [INSERT (SQL Graph)](../statements/insert-sql-graph.md)
241+
- [Graph processing with SQL Server and Azure SQL Database](../../relational-databases/graphs/sql-graph-overview.md)
242+
- [SHORTEST_PATH (Transact-SQL)](../../relational-databases/graphs/sql-graph-shortest-path.md)

0 commit comments

Comments
 (0)