Add example to create an index (#11751)

* Internalize SearchFieldTemplate.Save * Add example to create an index Fixes #9472
Azure · May 3, 2020 · 5454f64 · 5454f64
1 parent 988543e
commit 5454f64
Show file tree

Hide file tree

Showing 9 changed files with 429 additions and 11 deletions.
diff --git a/sdk/search/Azure.Search.Documents/README.md b/sdk/search/Azure.Search.Documents/README.md
@@ -266,7 +266,52 @@ SearchOptions options = new SearchOptions
 };
 SearchResults<Hotel> response = client.Search<Hotel>("luxury", options);
 // ...
-``` 
+```
+
+### Creating an index
+
+You can use the `SearchServiceClient` to create a search index. Fields can be
+defined using convenient `SimpleField`, `SearchableField`, or `ComplexField`
+classes. Indexes can also define suggesters, lexical analyzers, and more.
+
+```C# Snippet:Azure_Search_Tests_Samples_Readme_CreateIndex
+Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
+string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
+
+// Create a service client
+AzureKeyCredential credential = new AzureKeyCredential(key);
+SearchServiceClient client = new SearchServiceClient(endpoint, credential);
+
+// Create the index
+SearchIndex index = new SearchIndex("hotels")
+{
+    Fields =
+    {
+        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
+        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
+        new SearchableField("description") { Analyzer = LexicalAnalyzerName.EnLucene },
+        new SearchableField("tags", collection: true) { IsFilterable = true, IsFacetable = true },
+        new ComplexField("address")
+        {
+            Fields =
+            {
+                new SearchableField("streetAddress"),
+                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
+                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
+                new SearchableField("country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
+                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
+            }
+        }
+    },
+    Suggesters =
+    {
+        // Suggest query terms from both the hotelName and description fields.
+        new Suggester("sg", "hotelName", "description")
+    }
+};
+
+client.CreateIndex(index);
+```
 
 ### Adding documents to your index
 

diff --git a/sdk/search/Azure.Search.Documents/api/Azure.Search.Documents.netstandard2.0.cs b/sdk/search/Azure.Search.Documents/api/Azure.Search.Documents.netstandard2.0.cs
@@ -278,7 +278,6 @@ public partial class ComplexField : Azure.Search.Documents.Models.SearchFieldTem
     {
         public ComplexField(string name, bool collection = false) { }
         public System.Collections.Generic.IList<Azure.Search.Documents.Models.SearchFieldTemplate> Fields { get { throw null; } }
-        protected override void Save(Azure.Search.Documents.Models.SearchField field) { }
     }
     public partial class ConditionalSkill : Azure.Search.Documents.Models.SearchIndexerSkill
     {
@@ -1163,7 +1162,6 @@ public partial class SearchableField : Azure.Search.Documents.Models.SimpleField
         public Azure.Search.Documents.Models.LexicalAnalyzerName? IndexAnalyzer { get { throw null; } set { } }
         public Azure.Search.Documents.Models.LexicalAnalyzerName? SearchAnalyzer { get { throw null; } set { } }
         public System.Collections.Generic.IList<string> SynonymMaps { get { throw null; } }
-        protected override void Save(Azure.Search.Documents.Models.SearchField field) { }
     }
     public partial class SearchDocument : System.Dynamic.DynamicObject, System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<string, object>>, System.Collections.Generic.IDictionary<string, object>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, object>>, System.Collections.IEnumerable
     {
@@ -1239,7 +1237,6 @@ internal SearchFieldTemplate() { }
         public string Name { get { throw null; } }
         public Azure.Search.Documents.Models.SearchFieldDataType Type { get { throw null; } }
         public static implicit operator Azure.Search.Documents.Models.SearchField (Azure.Search.Documents.Models.SearchFieldTemplate value) { throw null; }
-        protected abstract void Save(Azure.Search.Documents.Models.SearchField field);
     }
     public partial class SearchIndex
     {
@@ -1516,7 +1513,6 @@ public SimpleField(string name, Azure.Search.Documents.Models.SearchFieldDataTyp
         public bool IsHidden { get { throw null; } set { } }
         public bool IsKey { get { throw null; } set { } }
         public bool IsSortable { get { throw null; } set { } }
-        protected override void Save(Azure.Search.Documents.Models.SearchField field) { }
     }
     public partial class SnowballTokenFilter : Azure.Search.Documents.Models.TokenFilter
     {

diff --git a/sdk/search/Azure.Search.Documents/src/Models/ComplexField.cs b/sdk/search/Azure.Search.Documents/src/Models/ComplexField.cs
@@ -29,7 +29,7 @@ public ComplexField(string name, bool collection = false) : base(name, collectio
         public IList<SearchFieldTemplate> Fields { get; } = new List<SearchFieldTemplate>();
 
         /// <inheritdoc/>
-        protected override void Save(SearchField field)
+        private protected override void Save(SearchField field)
         {
             // TODO: Remove allocation when https://github.com/Azure/autorest.csharp/issues/521 is fixed.
             IList<SearchField> fields = field.Fields ?? new List<SearchField>();

diff --git a/sdk/search/Azure.Search.Documents/src/Models/SearchFieldTemplate.cs b/sdk/search/Azure.Search.Documents/src/Models/SearchFieldTemplate.cs
@@ -40,7 +40,7 @@ private protected SearchFieldTemplate(string name, SearchFieldDataType type)
         /// Persists class-specific properties into the given <see cref="SearchField"/>.
         /// </summary>
         /// <param name="field">The <see cref="SearchField"/> into which properties are persisted.</param>
-        protected abstract void Save(SearchField field);
+        private protected abstract void Save(SearchField field);
 
         /// <summary>
         /// Casts a <see cref="SearchFieldTemplate"/> or derivative to a <see cref="SearchField"/>.

diff --git a/sdk/search/Azure.Search.Documents/src/Models/SearchableField.cs b/sdk/search/Azure.Search.Documents/src/Models/SearchableField.cs
@@ -53,7 +53,7 @@ public SearchableField(string name, bool collection = false) : base(name, collec
         public IList<string> SynonymMaps { get; } = new List<string>();
 
         /// <inheritdoc/>
-        protected override void Save(SearchField field)
+        private protected override void Save(SearchField field)
         {
             base.Save(field);
 

diff --git a/sdk/search/Azure.Search.Documents/src/Models/SimpleField.cs b/sdk/search/Azure.Search.Documents/src/Models/SimpleField.cs
@@ -60,7 +60,7 @@ public SimpleField(string name, SearchFieldDataType type) : base(name, type)
         public bool IsSortable { get; set; }
 
         /// <inheritdoc/>
-        protected override void Save(SearchField field)
+        private protected override void Save(SearchField field)
         {
             field.IsKey = IsKey;
             field.IsHidden = IsHidden;

diff --git a/sdk/search/Azure.Search.Documents/tests/Samples/Readme.cs b/sdk/search/Azure.Search.Documents/tests/Samples/Readme.cs
@@ -27,8 +27,12 @@ public Readme(bool async, SearchClientOptions.ServiceVersion serviceVersion)
 
         [Test]
         [SyncOnly]
-        public void Authenticate()
+        public async Task Authenticate()
         {
+            await using SearchResources resources = await SearchResources.GetSharedHotelsIndexAsync(this);
+            Environment.SetEnvironmentVariable("SEARCH_ENDPOINT", resources.Endpoint.ToString());
+            Environment.SetEnvironmentVariable("SEARCH_API_KEY", resources.PrimaryApiKey);
+
             #region Snippet:Azure_Search_Tests_Samples_Readme_Authenticate
             // Get the service endpoint and API key from the environment
             Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
@@ -174,6 +178,56 @@ public async Task Options()
             #endregion Snippet:Azure_Search_Tests_Samples_Readme_Options
         }
 
+        [Test]
+        [SyncOnly]
+        public async Task CreateIndex()
+        {
+            await using SearchResources resources = await SearchResources.CreateWithNoIndexesAsync(this);
+            Environment.SetEnvironmentVariable("SEARCH_ENDPOINT", resources.Endpoint.ToString());
+            Environment.SetEnvironmentVariable("SEARCH_API_KEY", resources.PrimaryApiKey);
+
+            #region Snippet:Azure_Search_Tests_Samples_Readme_CreateIndex
+            Uri endpoint = new Uri(Environment.GetEnvironmentVariable("SEARCH_ENDPOINT"));
+            string key = Environment.GetEnvironmentVariable("SEARCH_API_KEY");
+
+            // Create a service client
+            AzureKeyCredential credential = new AzureKeyCredential(key);
+            SearchServiceClient client = new SearchServiceClient(endpoint, credential);
+            /*@@*/ client = resources.GetServiceClient();
+
+            // Create the index
+            //@@SearchIndex index = new SearchIndex("hotels")
+            /*@@*/ SearchIndex index = new SearchIndex(Recording.Random.GetName())
+            {
+                Fields =
+                {
+                    new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
+                    new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
+                    new SearchableField("description") { Analyzer = LexicalAnalyzerName.EnLucene },
+                    new SearchableField("tags", collection: true) { IsFilterable = true, IsFacetable = true },
+                    new ComplexField("address")
+                    {
+                        Fields =
+                        {
+                            new SearchableField("streetAddress"),
+                            new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
+                            new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
+                            new SearchableField("country") { IsFilterable = true, IsSortable = true, IsFacetable = true },
+                            new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
+                        }
+                    }
+                },
+                Suggesters =
+                {
+                    // Suggest query terms from both the hotelName and description fields.
+                    new Suggester("sg", "hotelName", "description")
+                }
+            };
+
+            client.CreateIndex(index);
+            #endregion Snippet:Azure_Search_Tests_Samples_Readme_CreateIndex
+        }
+
         [Test]
         [SyncOnly]
         public async Task Index()

diff --git a/sdk/search/Azure.Search.Documents/tests/SessionRecords/Readme/Authenticate.json b/sdk/search/Azure.Search.Documents/tests/SessionRecords/Readme/Authenticate.json