You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/search/search-how-to-create-search-index.md
+69-79Lines changed: 69 additions & 79 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -36,13 +36,15 @@ Index creation is largely a schema definition exercise. Before creating one, you
36
36
37
37
Finally, all service tiers have [index limits](search-limits-quotas-capacity.md#index-limits) on the number of objects that you can create. For example, if you are experimenting on the Free tier, you can only have 3 indexes at any given time. Within the index itself, there are limits on the number of complex fields and collections.
38
38
39
-
## Mutable and immutable changes
39
+
## Allowed updates
40
40
41
-
To minimize churn in the design process, the following table describes which elements are fixed and flexible. Changing a fixed element requires an index rebuild, whereas flexible elements can be changed at any time without impacting the physical implementation.
41
+
A [Create Index](/rest/api/searchservice/create-index) operation creates the physical data structures (files and inverted indexes) on your search service. Your ability to update an existing index hinges on whether the modification invalidates those physical structures.
42
+
43
+
To minimize churn in the design process, the following table describes which elements are fixed and flexible in the schema. Changing a fixed element requires an index rebuild, whereas flexible elements can be changed at any time without impacting the physical implementation.
42
44
43
45
| Element | Mutable |
44
46
|---------|---------|
45
-
| Name | No |
47
+
| Name | No. Refer to [naming conventions](/rest/api/searchservice/naming-rules) when naming an index.|
46
48
| Key | No |
47
49
| Field names and types | No |
48
50
| Field attributes (searchable, filterable, facetable, sortable) | No. You can add new fields at any time, but changing an existing field is not supported. |
@@ -63,35 +65,88 @@ During development, plan on frequent rebuilds. Because physical structures are c
63
65
64
66
### [**Azure portal**](#tab/indexer-portal)
65
67
66
-
The portal provides two options for creating a search index: [**Import data wizard**](search-import-data-portal.md) and **Add Index** that provides fields for specifying an index schema.
68
+
Index design through the portal enforces requirements and schema rules for specific data types, such as disallowing full text search capabilities on numeric fields. In the portal, there are two options for creating a search index:
69
+
70
+
+**Add Index** is an embedded editor for specifying an index schema
71
+
+[**Import data*](search-import-data-portal.md) is a wizard
67
72
68
73
The wizard packs in additional operations by also creating an indexer, data source, and loading data. If this is more than what you want, you should just use **Add Index** or another approach.
69
74
70
-
The following screenshot shows where you can find **Add Index** and **Import data** on the command bar.
75
+
The following screenshot shows where you can find **Add Index** and **Import data** on the command bar. After an index is created, you can find it again in the Indexes tab.
71
76
72
77
:::image type="content" source="media/search-what-is-an-index/add-index.png" alt-text="Add index command" border="true":::
73
78
74
79
> [!Tip]
75
-
> Index design through the portal enforces requirements and schema rules for specific data types, such as disallowing full text search capabilities on numeric fields. Once you have a workable index, you can copy the JSON from the portal and add it to your solution.
80
+
> After creating an index in the portal, you can copy the JSON representation and add it to your application code.
76
81
77
82
### [**REST**](#tab/kstore-rest)
78
83
79
-
Both Postman and Visual Studio Code (with an extension for Azure Cognitive Search) can function as a search index client. Using either tool, you can connect to your search service and send [Create Index (REST)](/rest/api/searchservice/create-index) requests. There are numerous tutorials and examples that demonstrate REST clients for creating objects.
80
-
81
-
Start with either of these articles to learn about each client:
84
+
[**Create Index (REST)**](/rest/api/searchservice/create-index) is used to create an index. Both Postman and Visual Studio Code (with an extension for Azure Cognitive Search) can function as a search index client. Using either tool, you can connect to your search service and send requests:
82
85
83
86
+[Create a search index using REST and Postman](search-get-started-rest.md)
84
87
+[Get started with Visual Studio Code and Azure Cognitive Search](search-get-started-vs-code.md)
85
88
89
+
The REST API provides defaults for field attribution. For example, all Edm.String fields are searchable by default. Attributes are shown in full below for illustrative purposes, but you can omit attribution in cases where the default values apply.
90
+
86
91
Refer to the [Index operations (REST)](/rest/api/searchservice/index-operations) for help with formulating index requests.
87
92
88
-
### [**.NET SDK**](#tab/kstore-dotnet)
93
+
```json
94
+
POST https://[servicename].search.windows.net/indexes?api-version=[api-version]
For Cognitive Search, the Azure SDKs implement generally available features. As such, you can use any of the SDKs to create a search index. All of them provide a **SearchIndexClient** that has methods for creating and updating indexes.
The Azure SDK for .NET has [**SearchIndexClient**](/dotnet/api/azure.search.documents.indexes.searchindexclient) with methods for creating and updating indexes.
For more examples, see[azure-search-dotnet-samples/quickstart/v11/](https://github.com/Azure-Samples/azure-search-dotnet-samples/tree/master/quickstart/v11).
95
150
96
151
### [**Other SDKs**](#tab/other-sdks)
97
152
@@ -105,71 +160,6 @@ For Cognitive Search, the Azure SDKs implement generally available features. As
105
160
106
161
---
107
162
108
-
<!-- ## Define fields
109
-
110
-
A search document is defined by the `fields` collection. You will need fields for queries and keys. You will probably also need fields to support filters, facets, and sorts. You might also need fields for data that a user never sees, for example you might want fields for profit margins or marketing promotions that you can use to modify search rank.
111
-
112
-
One field of type Edm.String must be designated as the document key. It's used to uniquely identify each search document and is case-sensitive. You can retrieve a document by its key to populate a details page.
113
-
114
-
If incoming data is hierarchical in nature, assign the [complex type](search-howto-complex-data-types.md) data type to represent the nested structures. The built-in sample data set, Hotels, illustrates complex types using an Address (contains multiple sub-fields) that has a one-to-one relationship with each hotel, and a Rooms complex collection, where multiple rooms are associated with each hotel.
115
-
116
-
Assign any analyzers to string fields before the index is created. Do the same for suggesters if you want to enable autocomplete on specific fields. -->
117
-
118
-
<!-- <a name="index-attributes"></a>
119
-
120
-
### Attributes
121
-
122
-
Field attributes determine how a field is used, such as whether it is used in full text search, faceted navigation, sort operations, and so forth.
123
-
124
-
String fields are often marked as "searchable" and "retrievable". Fields used to narrow search results include "sortable", "filterable", and "facetable".
125
-
126
-
|Attribute|Description|
127
-
|---------------|-----------------|
128
-
|"searchable" |Full-text searchable, subject to lexical analysis such as word-breaking during indexing. If you set a searchable field to a value like "sunny day", internally it will be split into the individual tokens "sunny" and "day". For details, see [How full text search works](search-lucene-query-architecture.md).|
129
-
|"filterable" |Referenced in $filter queries. Filterable fields of type `Edm.String` or `Collection(Edm.String)` do not undergo word-breaking, so comparisons are for exact matches only. For example, if you set such a field f to "sunny day", `$filter=f eq 'sunny'` will find no matches, but `$filter=f eq 'sunny day'` will. |
130
-
|"sortable" |By default the system sorts results by score, but you can configure sort based on fields in the documents. Fields of type `Collection(Edm.String)` cannot be "sortable". |
131
-
|"facetable" |Typically used in a presentation of search results that includes a hit count by category (for example, hotels in a specific city). This option cannot be used with fields of type `Edm.GeographyPoint`. Fields of type `Edm.String` that are filterable, "sortable", or "facetable" can be at most 32 kilobytes in length. For details, see [Create Index (REST API)](/rest/api/searchservice/create-index).|
132
-
|"key" |Unique identifier for documents within the index. Exactly one field must be chosen as the key field and it must be of type `Edm.String`.|
133
-
|"retrievable" |Determines whether the field can be returned in a search result. This is useful when you want to use a field (such as *profit margin*) as a filter, sorting, or scoring mechanism, but do not want the field to be visible to the end user. This attribute must be `true` for `key` fields.|
134
-
135
-
Although you can add new fields at any time, existing field definitions are locked in for the lifetime of the index. For this reason, developers typically use the portal for creating simple indexes, testing ideas, or using the portal pages to look up a setting. Frequent iteration over an index design is more efficient if you follow a code-based approach so that you can rebuild the index easily.
136
-
137
-
> [!NOTE]
138
-
> The APIs you use to build an index have varying default behaviors. For the [REST APIs](/rest/api/searchservice/Create-Index), most attributes are enabled by default (for example, "searchable" and "retrievable" are true for string fields) and you often only need to set them if you want to turn them off. For the .NET SDK, the opposite is true. On any property you do not explicitly set, the default is to disable the corresponding search behavior unless you specifically enable it.
139
-
140
-
<a name="index-size"></a>
141
-
142
-
## Attributes and index size (storage implications)
143
-
144
-
The size of an index is determined by the size of the documents you upload, plus index configuration, such as whether you include suggesters, and how you set attributes on individual fields.
145
-
146
-
The following screenshot illustrates index storage patterns resulting from various combinations of attributes. The index is based on the **real estate sample index**, which you can create easily using the Import data wizard. Although the index schemas are not shown, you can infer the attributes based on the index name. For example, *realestate-searchable* index has the "searchable" attribute selected and nothing else, *realestate-retrievable* index has the "retrievable" attribute selected and nothing else, and so forth.
147
-
148
-
149
-
150
-
Although these index variants are artificial, we can refer to them for broad comparisons of how attributes affect storage. Does setting "retrievable" increase index size? No. Does adding fields to a **suggester** increase index size? Yes.
151
-
152
-
Making a field filterable or sortable also adds to storage consumption because filtered and sorted fields are not tokenized so that character sequences can be matched verbatim.
153
-
154
-
Also not reflected in the above table is the impact of [analyzers](search-analyzers.md). If you are using the edgeNgram tokenizer to store verbatim sequences of characters (a, ab, abc, abcd), the size of the index will be larger than if you used a standard analyzer.
155
-
156
-
> [!Note]
157
-
> Storage architecture is considered an implementation detail of Azure Cognitive Search and could change without notice. There is no guarantee that current behavior will persist in the future.
158
-
159
-
<a name="corsoptions"></a>
160
-
161
-
## About `corsOptions`
162
-
163
-
Index schemas include a section for setting `corsOptions`. Client-side JavaScript cannot call any APIs by default since the browser will prevent all cross-origin requests. To allow cross-origin queries to your index, enable CORS (Cross-Origin Resource Sharing) by setting the **corsOptions** attribute. For security reasons, only query APIs support CORS.
164
-
165
-
The following options can be set for CORS:
166
-
167
-
+ **allowedOrigins** (required): This is a list of origins that will be granted access to your index. This means that any JavaScript code served from those origins will be allowed to query your index (assuming it provides the correct api-key). Each origin is typically of the form `protocol://<fully-qualified-domain-name>:<port>` although `<port>` is often omitted. See [Cross-origin resource sharing (Wikipedia)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) for more details.
168
-
169
-
If you want to allow access to all origins, include `*` as a single item in the **allowedOrigins** array. *This is not recommended practice for production search services* but it is often useful for development and debugging.
170
-
171
-
+ **maxAgeInSeconds** (optional): Browsers use this value to determine the duration (in seconds) to cache CORS preflight responses. This must be a non-negative integer. The larger this value is, the better performance will be, but the longer it will take for CORS policy changes to take effect. If it is not set, a default duration of 5 minutes will be used. -->
172
-
173
163
## Next steps
174
164
175
165
Use the following links to become familiar with loading an index with data.
Copy file name to clipboardExpand all lines: articles/search/search-what-is-an-index.md
+5-3Lines changed: 5 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,9 +15,11 @@ ms.date: 11/08/2021
15
15
16
16
Cognitive Search stores searchable content used for full text and filtered queries in a *search index*. An index is defined by a schema and saved to the service, with data import following as a second step.
17
17
18
-
Indexes contain *search documents*. Conceptually, a document is a single unit of searchable data in your index. A retailer might have a document for each product, a news organization might have a document for each article, and so forth. Mapping these concepts to more familiar database equivalents: a *search index* equates to a *table*, and *documents* are roughly equivalent to *rows* in a table.
18
+
This article is an introduction to search indexes. Prefer to get started? See [Create a search index](search-hwo-to-create-search-index.md).
19
19
20
-
## What's an index schema?
20
+
## What's a search index?
21
+
22
+
In Cognitive Search, indexes contain *search documents*. Conceptually, a document is a single unit of searchable data in your index. For example, a retailer might have a document for each product, a news organization might have a document for each article, and so forth. Mapping these concepts to more familiar database equivalents: a *search index* equates to a *table*, and *documents* are roughly equivalent to *rows* in a table.
21
23
22
24
The physical structure of an index is determined by the schema. The 'fields' collection is typically the largest part of an index, where each field is named, assigned a [data type](/rest/api/searchservice/Supported-data-types), and attributed with allowable behaviors that determine how it is used.
23
25
@@ -126,7 +128,7 @@ You can get hands-on experience creating an index using almost any sample or wal
126
128
127
129
But you'll also want to become familiar with methodologies for loading an index with data. Index definition and data import strategies are defined in tandem. The following articles provide more information about creating and loading an index.
128
130
129
-
+[Creating a search index](search-how-to-create-search-index.md)
131
+
+[Create a search index](search-how-to-create-search-index.md)
0 commit comments