github.com/opensearch-project/opensearch-go/v2@v2.3.0/opensearchapi/doc.go (about)

     1  // SPDX-License-Identifier: Apache-2.0
     2  //
     3  // The OpenSearch Contributors require contributions made to
     4  // this file be licensed under the Apache-2.0 license or a
     5  // compatible open source license.
     6  //
     7  // Modifications Copyright OpenSearch Contributors. See
     8  // GitHub history for details.
     9  
    10  // Licensed to Elasticsearch B.V. under one or more contributor
    11  // license agreements. See the NOTICE file distributed with
    12  // this work for additional information regarding copyright
    13  // ownership. Elasticsearch B.V. licenses this file to you under
    14  // the Apache License, Version 2.0 (the "License"); you may
    15  // not use this file except in compliance with the License.
    16  // You may obtain a copy of the License at
    17  //
    18  //    http://www.apache.org/licenses/LICENSE-2.0
    19  //
    20  // Unless required by applicable law or agreed to in writing,
    21  // software distributed under the License is distributed on an
    22  // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    23  // KIND, either express or implied.  See the License for the
    24  // specific language governing permissions and limitations
    25  // under the License.
    26  
    27  /*
    28  Package opensearchapi provides the Go API for OpenSearch.
    29  
    30  It is automatically included in the client provided by the
    31  github.com/opensearch-project/opensearch-go package:
    32  
    33  	client, _ := opensearch.NewDefaultClient()
    34  	res, _ := client.Info()
    35  	log.Println(res)
    36  
    37  For each OpenSearch API, such as "Index", the package exports two corresponding types:
    38  a function and a struct.
    39  
    40  The function type allows you to call the OpenSearch API as a method on the client,
    41  passing the parameters as arguments:
    42  
    43  	res, err := client.Index(
    44  		"test",                                  // Index name
    45  		strings.NewReader(`{"title" : "Test"}`), // Document body
    46  		client.Index.WithDocumentID("1"),            // Document ID
    47  		client.Index.WithRefresh("true"),            // Refresh
    48  	)
    49  	if err != nil {
    50  		log.Fatalf("ERROR: %s", err)
    51  	}
    52  	defer res.Body.Close()
    53  
    54  	log.Println(res)
    55  
    56  	// => [201 Created] {"_index":"test","_type":"_doc","_id":"1" ...
    57  
    58  The struct type allows for a more hands-on approach, where you create a new struct, with the
    59  request configuration as fields, and call the Do() method
    60  with a context and the client as arguments:
    61  
    62  	req := opensearchapi.IndexRequest{
    63  		Index:      "test",                                  // Index name
    64  		Body:       strings.NewReader(`{"title" : "Test"}`), // Document body
    65  		DocumentID: "1",                                     // Document ID
    66  		Refresh:    "true",                                  // Refresh
    67  	}
    68  
    69  	res, err := req.Do(context.Background(), client)
    70  	if err != nil {
    71  		log.Fatalf("Error getting response: %s", err)
    72  	}
    73  	defer res.Body.Close()
    74  
    75  	log.Println(res)
    76  
    77  	// => [200 OK] {"_index":"test","_type":"_doc","_id":"1","_version":2 ...
    78  
    79  The function type is a wrapper around the struct, and allows
    80  to configure and perform the request in a more expressive way.
    81  It has a minor overhead compared to using a struct directly;
    82  refer to the opensearchapi_benchmark_test.go suite for concrete numbers.
    83  
    84  See the documentation for each API function or struct at
    85  https://godoc.org/github.com/opensearch-project/opensearch-go,
    86  or locally by:
    87  
    88  	go doc github.com/opensearch-project/opensearch-go/opensearchapi Index
    89  	go doc github.com/opensearch-project/opensearch-go/opensearchapi IndexRequest
    90  
    91  Response
    92  
    93  The opensearchapi.Response type is a lightweight wrapper around http.Response.
    94  
    95  The res.Body field is an io.ReadCloser, leaving the JSON parsing to the
    96  calling code, in the interest of performance and flexibility
    97  (eg. to allow using a custom JSON parser).
    98  
    99  It is imperative to close the response body for a non-nil response.
   100  
   101  The Response type implements a couple of convenience methods for accessing
   102  the status, checking an error status code or printing
   103  the response body for debugging purposes.
   104  
   105  */
   106  package opensearchapi