Added API guide for document lifecycle.

Signed-off-by: Djcarrillo6 <[email protected]> Added Movie class code to guide setup example. Signed-off-by: Djcarrillo6 <[email protected]>
opensearch-project · Oct 13, 2023 · f9ffce8 · f9ffce8
1 parent 1b4bb87
commit f9ffce8
Showing 1 changed file with 216 additions and 0 deletions.
diff --git a/guides/document_lifecycle.md b/guides/document_lifecycle.md
@@ -0,0 +1,216 @@
+# Document Lifecycle
+This guide covers OpenSearch Ruby Client API actions for Document Lifecycle. You'll learn how to create, read, update, and delete documents in your OpenSearch cluster. Whether you're new to OpenSearch or an experienced user, this guide provides the information you need to manage your document lifecycle effectively.
+
+## Setup
+Assuming you have OpenSearch running locally on port 9200, you can create a client instance with the following code:
+```csharp
+    var node = new Uri("https://localhost:9200");
+    var config = new ConnectionSettings(node)
+        .ServerCertificateValidationCallback(CertificateValidations.AllowAll)
+        .BasicAuthentication("admin", "admin")
+        .DisableDirectStreaming();
+
+    var client = new OpenSearchClient(config);
+
+    class Movie
+    {
+        public string Title { get; set; }
+        public string Director { get; set; }
+        public int Year { get; set; }
+    }
+```
+
+Next, create an index named `movies` with the default settings:
+```csharp
+    var createIndexResponse = client.Indices.Create("movies", c => c
+        .Map(m => m
+            .Properties(p => p
+                .Text(t => t
+                    .Name("director")
+                )
+                .Text(t => t
+                    .Name("title")
+                )
+                .Number(n => n
+                    .Name("year")
+                )
+            )
+        )
+    );
+```
+
+
+## Document API Actions
+
+### Create a new document with specified ID
+To create a new document, use the `Create` or `Index` API action. The following code creates two new documents with IDs of `1` and `2`:
+```csharp
+    var createResponse = client.Create(new Movie
+    {
+        Title = "The Godfather",
+        Director = "Francis Ford Coppola",
+        Year = 1972
+    }, i => i.Index("movies").Id(1));
+
+    var indexResponse = client.Index(new Movie
+    {
+        Title = "The Godfather: Part II",
+        Director = "Francis Ford Coppola",
+        Year = 1974
+    }, i => i.Index("movies").Id(2));
+```
+
+Note that the `Create` action is NOT idempotent. If you try to create a document with an ID that already exists, the request will fail:
+```csharp
+    var createResponse = client.Create(new Movie
+    {
+        Title = "The Godfather: Part II",
+        Director = "Francis Ford Coppola",
+        Year = 1974
+    }, i => i.Index("movies").Id(2)); // Fails because document with ID 2 already exists
+```
+
+The `Index` action, on the other hand, is idempotent. If you try to index a document with an existing ID, the request will succeed and overwrite the existing document. Note that no new document will be created in this case. You can think of the `Index` action as an upsert:
+
+```csharp
+    var indexResponse = client.Index(new Movie
+    {
+        Title = "The Godfather: Part III",
+        Director = "Francis Ford Coppola",
+        Year = 1974
+    }, i => i.Index("movies").Id(2));
+
+    // Succeeds and overwrites the existing document
+    var indexResponse = client.Index(new Movie
+    {
+        Title = "The Godfather: Part IV",
+        Director = "Francis Ford Coppola",
+        Year = 1974
+    }, i => i.Index("movies").Id(2));
+```
+
+
+### Create a new document with auto-generated ID
+You can also create a new document with an auto-generated ID by omitting the `Id` parameter. The following code creates documents with an auto-generated IDs in the `movies` index:
+```csharp
+    var indexResponse = client.Index(new Movie
+    {
+        Title = "The Godfather: Part V",
+        Director = "Francis Ford Coppola",
+        Year = 1974
+    }, i => i.Index("movies"));
+```
+
+In this case, the ID of the created document in the `Result` field of the response body:
+```csharp
+    {
+        "_index": "movies",
+        "_type": "_doc",
+        "_id": "1",
+        "_version": 1,
+        "result": "created",
+        "_shards": {
+            "total": 2,
+            "successful": 1,
+            "failed": 0
+        },
+        "_seq_no": 0,
+        "_primary_term": 1
+    }
+```
+
+
+### Get a document
+To get a document, use the `Get` API action. The following code gets the document with ID `1` from the `movies` index:
+```csharp
+    var getResponse = client.Get<Movie>(1, g => g.Index("movies"));
+```
+
+You can also use `SourceIncludes` and `SourceExcludes` parameters to specify which fields to include or exclude in the response:
+```csharp
+    var getResponse = client.Get<Movie>(1, c => c
+        .Index("movies")
+        .SourceIncludes(f => f.Director, f => f.Title)
+        .SourceExcludes(f => f.Year)
+    );
+```
+
+
+### Get multiple documents
+To get multiple documents, use the `MultiGet` API action. The following code gets the documents with IDs `1` and `2` from the `movies` index:
+```csharp
+    var multiGetResponse = client.GetMany<Movie>(new List<long> { 1, 2 }, "movies");
+```
+
+
+### Check if a document exists
+To check if a document exists, use the `DocumentExists` API action. The following code checks if the document with ID `1` exists in the `movies` index:
+```csharp
+    var existsResponse = client.DocumentExists<Movie>(1, d => d.Index("movies"));
+```
+
+
+### Update a document
+To update a document, use the `Update` API action. The following code updates the `Year` field of the document with ID `1` in the `movies`  index:
+```csharp
+    var updateResponse =client.Update<Movie>(1, u => u
+        .Index("movies")
+        .Doc(new Movie { Year = 2023 })
+    );
+```
+
+
+Alternatively, you can use the `Script` parameter to update a document using a script. The following code increments the `Year` field of the of document with ID `1` by 5 using painless script, the default scripting language in OpenSearch:
+```csharp
+    var updateResponse =  client.Update<Movie>(1, u => u
+        .Index("movies")
+        .Script(s => s.Source("ctx._source.year += params.count").Params(p => p.Add("count", 5)))
+    );
+```
+
+Note that while both `Update` and `Index` actions perform updates, they are not the same. The `Update` action is a partial update, while the `Index` action is a full update. The `Update` action only updates the fields that are specified in the request body, while the `Index` action overwrites the entire document with the new document.
+
+
+### Update multiple documents by query
+To update documents that match a query, use the `UpdateByQuery` API action. The following code decreases the `Year` field of all documents with `Year` greater than 2023:
+```csharp
+    var updateByQueryResponse = client.UpdateByQuery<Movie>(u => u
+        .Index("movies")
+        .Query(q => q
+            .Range(r => r
+                .Field(f => f.Year)
+                .GreaterThan(2023)
+            )
+        )
+        .Script(s => s.Source("ctx._source.year -= params.count").Params(p => p.Add("count", 5)))
+    );
+```
+
+
+### Delete a document
+To delete a document, use the `Delete` API action. The following code deletes the document with ID `1`: 
+```csharp
+    var deleteResponse = client.Delete<Movie>(1, d => d.Index("movies"));
+```
+
+
+### Delete multiple documents by query
+To delete documents that match a query, use the `DeleteByQuery` API action. The following code deletes all documents with `Year` greater than 2023:
+```csharp
+    var deleteByQueryResponse = client.DeleteByQuery<Movie>(d => d
+        .Index("movies")
+        .Query(q => q
+            .Range(r => r
+                .Field(f => f.Year)
+                .GreaterThan(1965)
+            )
+        )
+    );
+```
+
+
+## Cleanup
+To clean up the resources created in this guide, delete the `movies` index:
+```csharp
+    var deleteIndexResponse = client.Indices.Delete("movies");
+```