Skip to content

Commit 1ae672b

Browse files
HeidiSteenHeidiSteen
committed
Test examples for ismatch function
1 parent 7fe6e39 commit 1ae672b

File tree

1 file changed

+196
-27
lines changed

1 file changed

+196
-27
lines changed

‎articles/search/search-query-odata-full-text-search-functions.md

Lines changed: 196 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -10,25 +10,15 @@ ms.service: azure-ai-search
1010
ms.custom:
1111
- ignite-2023
1212
ms.topic: reference
13-
ms.date: 09/16/2021
14-
translation.priority.mt:
15-
- "de-de"
16-
- "es-es"
17-
- "fr-fr"
18-
- "it-it"
19-
- "ja-jp"
20-
- "ko-kr"
21-
- "pt-br"
22-
- "ru-ru"
23-
- "zh-cn"
24-
- "zh-tw"
13+
ms.date: 07/10/2025
14+
2515
---
2616
# OData full-text search functions in Azure AI Search - `search.ismatch` and `search.ismatchscoring`
2717

28-
Azure AI Search supports full-text search in the context of [OData filter expressions](query-odata-filter-orderby-syntax.md) via the `search.ismatch` and `search.ismatchscoring` functions. These functions allow you to combine full-text search with strict Boolean filtering in ways that are not possible just by using the top-level `search` parameter of the [Search API](/rest/api/searchservice/documents/search-post).
18+
Azure AI Search supports full-text search in the context of [OData filter expressions](query-odata-filter-orderby-syntax.md) via the `search.ismatch` and `search.ismatchscoring` functions. These functions allow you to combine full-text search with strict Boolean filtering in ways that aren't possible just by using the top-level `search` parameter of the [Search API](/rest/api/searchservice/documents/search-post).
2919

3020
> [!NOTE]
31-
> The `search.ismatch` and `search.ismatchscoring` functions are only supported in filters in the [Search API](/rest/api/searchservice/documents/search-post). They are not supported in the [Suggest](/rest/api/searchservice/documents/suggest-post) or [Autocomplete](/rest/api/searchservice/documents/autocomplete-post) APIs.
21+
> The `search.ismatch` and `search.ismatchscoring` functions are only supported in filters in the [Search API](/rest/api/searchservice/documents/search-post). They aren't supported in the [Suggest](/rest/api/searchservice/documents/suggest-post) or [Autocomplete](/rest/api/searchservice/documents/autocomplete-post) APIs.
3222
3323
## Syntax
3424

@@ -58,7 +48,7 @@ An interactive syntax diagram is also available:
5848
5949
### search.ismatch
6050

61-
The `search.ismatch` function evaluates a full-text search query as a part of a filter expression. The documents that match the search query will be returned in the result set. The following overloads of this function are available:
51+
The `search.ismatch` function evaluates a full-text search query as a part of a filter expression. Matching documents are returned in the result set. The following overloads of this function are available:
6252

6353
- `search.ismatch(search)`
6454
- `search.ismatch(search, searchFields)`
@@ -69,21 +59,21 @@ The parameters are defined in the following table:
6959
| Parameter name | Type | Description |
7060
| --- | --- | --- |
7161
| `search` | `Edm.String` | The search query (in either [simple](query-simple-syntax.md) or [full](query-lucene-syntax.md) Lucene query syntax). |
72-
| `searchFields` | `Edm.String` | Comma-separated list of searchable fields to search in; defaults to all searchable fields in the index. When using [fielded search](query-lucene-syntax.md#bkmk_fields) in the `search` parameter, the field specifiers in the Lucene query override any fields specified in this parameter. |
62+
| `searchFields` | `Edm.String` | Comma-separated list of searchable fields to search in; defaults to all searchable fields in the index. When you use [fielded search](query-lucene-syntax.md#bkmk_fields) in the `search` parameter, the field specifiers in the Lucene query override any fields specified in this parameter. |
7363
| `queryType` | `Edm.String` | `'simple'` or `'full'`; defaults to `'simple'`. Specifies what query language was used in the `search` parameter. |
74-
| `searchMode` | `Edm.String` | `'any'` or `'all'`, defaults to `'any'`. Indicates whether any or all of the search terms in the `search` parameter must be matched in order to count the document as a match. When using the [Lucene Boolean operators](query-lucene-syntax.md#bkmk_boolean) in the `search` parameter, they will take precedence over this parameter. |
64+
| `searchMode` | `Edm.String` | `'any'` or `'all'`, defaults to `'any'`. Indicates whether any or all of the search terms in the `search` parameter must be matched in order to count the document as a match. When you use the [Lucene Boolean operators](query-lucene-syntax.md#bkmk_boolean) in the `search` parameter, they take precedence over this parameter. |
7565

7666
All the above parameters are equivalent to the corresponding [search request parameters in the Search API](/rest/api/searchservice/documents/search-post).
7767

78-
The `search.ismatch` function returns a value of type `Edm.Boolean`, which allows you to compose it with other filter sub-expressions using the Boolean [logical operators](search-query-odata-logical-operators.md).
68+
The `search.ismatch` function returns a value of type `Edm.Boolean`, which allows you to compose it with other filter subexpressions using the Boolean [logical operators](search-query-odata-logical-operators.md).
7969

8070
> [!NOTE]
81-
> Azure AI Search does not support using `search.ismatch` or `search.ismatchscoring` inside lambda expressions. This means it is not possible to write filters over collections of objects that can correlate full-text search matches with strict filter matches on the same object. For more details on this limitation as well as examples, see [Troubleshooting collection filters in Azure AI Search](search-query-troubleshoot-collection-filters.md). For more in-depth information on why this limitation exists, see [Understanding collection filters in Azure AI Search](search-query-understand-collection-filters.md).
71+
> Azure AI Search doesn't support using `search.ismatch` or `search.ismatchscoring` inside lambda expressions. This means it isn't possible to write filters over collections of objects that can correlate full-text search matches with strict filter matches on the same object. For more information on this limitation as well as examples, see [Troubleshooting collection filters in Azure AI Search](search-query-troubleshoot-collection-filters.md). For more in-depth information on why this limitation exists, see [Understanding collection filters in Azure AI Search](search-query-understand-collection-filters.md).
8272
8373

8474
### search.ismatchscoring
8575

86-
The `search.ismatchscoring` function, like the `search.ismatch` function, returns `true` for documents that match the full-text search query passed as a parameter. The difference between them is that the relevance score of documents matching the `search.ismatchscoring` query will contribute to the overall document score, while in the case of `search.ismatch`, the document score won't be changed. The following overloads of this function are available with parameters identical to those of `search.ismatch`:
76+
The `search.ismatchscoring` function, like the `search.ismatch` function, returns `true` for documents that match the full-text search query passed as a parameter. The difference between them is that the relevance score of documents matching the `search.ismatchscoring` query contributes to the overall document score, whereas for `search.ismatch`, the document score doesn't change. The following overloads of this function are available with parameters identical to those of `search.ismatch`:
8777

8878
- `search.ismatchscoring(search)`
8979
- `search.ismatchscoring(search, searchFields)`
@@ -99,10 +89,36 @@ Find documents with the word "waterfront". This filter query is identical to a [
9989
search.ismatchscoring('waterfront')
10090
```
10191

102-
Find documents with the word "hostel" and rating greater or equal to 4, or documents with the word "motel" and rating equal to 5. Note, this request could not be expressed without the `search.ismatchscoring` function.
92+
Here's the full query syntax for this request, which you can run in Search Explorer in the Azure portal. Output consists of matches on waterfront, water, and front.
93+
94+
```json
95+
{
96+
"search": "*",
97+
"select": "HotelId, HotelName, Description",
98+
"searchMode": "all",
99+
"queryType": "simple",
100+
"count": true,
101+
"filter": "search.ismatchscoring('waterfront')"
102+
}
103+
```
104+
105+
Find documents with the word "pool" and rating greater or equal to 4, or documents with the word "motel" and equal to 3.2. Note, this request couldn't be expressed without the `search.ismatchscoring` function.
103106

104107
```odata-filter-expr
105-
search.ismatchscoring('hostel') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 5
108+
search.ismatchscoring('pool') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 3.2
109+
```
110+
111+
Here's the full query syntax for this request for Search Explorer. Output consists of matches on hotels with pools having a rating greater than 4, *or* motels with a rating equal to 3.2.
112+
113+
```json
114+
{
115+
"search": "*",
116+
"select": "HotelId, HotelName, Description, Tags, Rating",
117+
"searchMode": "all",
118+
"queryType": "simple",
119+
"count": true,
120+
"filter": "search.ismatchscoring('pool') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 3.2"
121+
}
106122
```
107123

108124
Find documents without the word "luxury".
@@ -111,26 +127,179 @@ Find documents without the word "luxury".
111127
not search.ismatch('luxury')
112128
```
113129

114-
Find documents with the phrase "ocean view" or rating equal to 5. The `search.ismatchscoring` query will be executed only against fields `HotelName` and `Rooms/Description`.
130+
Find documents with the phrase "ocean" or rating equal to 3.2. The `search.ismatchscoring` query is executed only against fields `HotelName` and `Description`.
115131

116-
Documents that matched only the second clause of the disjunction will be returned too -- hotels with `Rating` equal to 5. To make it clear that those documents didn't match any of the scored parts of the expression, they will be returned with score equal to zero.
132+
Documents that matched only the second clause of the disjunction will be returned too -- hotels with `Rating` equal to `3.2`. To make it clear that those documents didn't match any of the scored parts of the expression, they're returned with score equal to zero.
117133

118-
```odata-filter-expr
119-
search.ismatchscoring('"ocean view"', 'Rooms/Description,HotelName') or Rating eq 5
134+
```json
135+
{
136+
"search": "*",
137+
"select": "HotelId, HotelName, Description, Rating",
138+
"searchMode": "all",
139+
"queryType": "full",
140+
"count": true,
141+
"filter": "search.ismatchscoring('ocean', 'Description,HotelName') or Rating eq 3.2"
142+
}
143+
```
144+
145+
Output consists of 4 matches: hotels that mention "ocean" in the Description or Hotel Name, or hotels with a rating of 3.2.
146+
147+
```json
148+
{
149+
"@odata.count": 4,
150+
"value": [
151+
{
152+
"@search.score": 1.6076145,
153+
"HotelId": "18",
154+
"HotelName": "Ocean Water Resort & Spa",
155+
"Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
156+
"Rating": 4.2
157+
},
158+
{
159+
"@search.score": 1.0594962,
160+
"HotelId": "41",
161+
"HotelName": "Windy Ocean Motel",
162+
"Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
163+
"Rating": 3.5
164+
},
165+
{
166+
"@search.score": 0,
167+
"HotelId": "40",
168+
"HotelName": "Trails End Motel",
169+
"Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
170+
"Rating": 3.2
171+
},
172+
{
173+
"@search.score": 0,
174+
"HotelId": "26",
175+
"HotelName": "Planetary Plaza & Suites",
176+
"Description": "Extend Your Stay. Affordable home away from home, with amenities like free Wi-Fi, full kitchen, and convenient laundry service.",
177+
"Rating": 3.2
178+
}
179+
]
180+
}
120181
```
121182

122-
Find documents where the terms "hotel" and "airport" are within 5 words from each other in the description of the hotel, and where smoking is not allowed in at least some of the rooms. This query uses the [full Lucene query language](query-lucene-syntax.md).
183+
Find documents where the terms "hotel" and "airport" are within 5 words from each other in the description of the hotel, and where smoking isn't allowed in at least some of the rooms.
123184

124185
```odata-filter-expr
125186
search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and Rooms/any(room: not room/SmokingAllowed)
126187
```
127188

189+
Here's the full query syntax. To run in Search Explorer, escape the interior quotation marks with a backslash character.
190+
191+
```json
192+
{
193+
"search": "*",
194+
"select": "HotelId, HotelName, Description, Tags, Rating",
195+
"searchMode": "all",
196+
"queryType": "simple",
197+
"count": true,
198+
"filter": "search.ismatch('\"hotel airport\"~5', 'Description', 'full', 'any') and Rooms/any(room: not room/SmokingAllowed)"
199+
}
200+
```
201+
202+
Output consists of a single document where the terms "hotel" and "airport" are within 5 words distance. Smoking is allowed for several rooms in most hotels, including the one in this search result.
203+
204+
```json
205+
{
206+
"@odata.count": 1,
207+
"value": [
208+
{
209+
"@search.score": 1,
210+
"HotelId": "40",
211+
"HotelName": "Trails End Motel",
212+
"Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
213+
"Tags": [
214+
"bar",
215+
"free wifi",
216+
"restaurant"
217+
],
218+
"Rating": 3.2
219+
}
220+
]
221+
}
222+
```
223+
128224
Find documents that have a word that starts with the letters "lux" in the Description field. This query uses [prefix search](query-simple-syntax.md#prefix-queries) in combination with `search.ismatch`.
129225

130226
```odata-filter-expr
131227
search.ismatch('lux*', 'Description')
132228
```
133229

230+
Here's a full query:
231+
232+
```json
233+
{
234+
"search": "*",
235+
"select": "HotelId, HotelName, Description, Tags, Rating",
236+
"searchMode": "all",
237+
"queryType": "simple",
238+
"count": true,
239+
"filter": "search.ismatch('lux*', 'Description')"
240+
}
241+
```
242+
243+
Here's the output:
244+
245+
```json
246+
{
247+
"@odata.count": 4,
248+
"value": [
249+
{
250+
"@search.score": 1,
251+
"HotelId": "18",
252+
"HotelName": "Ocean Water Resort & Spa",
253+
"Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
254+
"Tags": [
255+
"view",
256+
"pool",
257+
"restaurant"
258+
],
259+
"Rating": 4.2
260+
},
261+
{
262+
"@search.score": 1,
263+
"HotelId": "13",
264+
"HotelName": "Luxury Lion Resort",
265+
"Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.",
266+
"Tags": [
267+
"bar",
268+
"concierge",
269+
"restaurant"
270+
],
271+
"Rating": 4.1
272+
},
273+
{
274+
"@search.score": 1,
275+
"HotelId": "16",
276+
"HotelName": "Double Sanctuary Resort",
277+
"Description": "5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.",
278+
"Tags": [
279+
"view",
280+
"pool",
281+
"restaurant",
282+
"bar",
283+
"continental breakfast"
284+
],
285+
"Rating": 4.2
286+
},
287+
{
288+
"@search.score": 1,
289+
"HotelId": "14",
290+
"HotelName": "Twin Vortex Hotel",
291+
"Description": "New experience in the making. Be the first to experience the luxury of the Twin Vortex. Reserve one of our newly-renovated guest rooms today.",
292+
"Tags": [
293+
"bar",
294+
"restaurant",
295+
"concierge"
296+
],
297+
"Rating": 4.4
298+
}
299+
]
300+
}
301+
```
302+
134303
## Next steps
135304

136305
- [Filters in Azure AI Search](search-filters.md)

0 commit comments

Comments
 (0)