db_example_test.go

Documentation: github.com/go-kivik/kivik/v4

     1  // Licensed under the Apache License, Version 2.0 (the "License"); you may not
     2  // use this file except in compliance with the License. You may obtain a copy of
     3  // the License at
     4  //
     5  //  http://www.apache.org/licenses/LICENSE-2.0
     6  //
     7  // Unless required by applicable law or agreed to in writing, software
     8  // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
     9  // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
    10  // License for the specific language governing permissions and limitations under
    11  // the License.
    12  
    13  package kivik_test
    14  
    15  import (
    16  	"context"
    17  	"encoding/json"
    18  	"fmt"
    19  
    20  	kivik "github.com/go-kivik/kivik/v4"
    21  )
    22  
    23  var db = &kivik.DB{}
    24  
    25  // Storing a document is done with Put or CreateDoc, which correspond to
    26  // `PUT /{db}/{doc}` and `POST /{db}` respectively. In most cases, you should
    27  // use Put.
    28  func ExampleDB_CreateDoc() {
    29  	type Animal struct {
    30  		ID       string `json:"_id"`
    31  		Rev      string `json:"_rev,omitempty"`
    32  		Feet     int    `json:"feet"`
    33  		Greeting string `json:"greeting"`
    34  	}
    35  
    36  	cow := Animal{Feet: 4, Greeting: "moo"}
    37  	docID, rev, err := db.CreateDoc(context.TODO(), cow)
    38  	if err != nil {
    39  		panic(err)
    40  	}
    41  	cow.ID = docID
    42  	cow.Rev = rev
    43  }
    44  
    45  var cow struct {
    46  	Rev      string
    47  	Greeting string
    48  }
    49  
    50  // Updating a document is the same as storing one, except that the `_rev`
    51  // parameter must match that stored on the server.
    52  func ExampleDB_Put() {
    53  	cow.Rev = "1-6e609020e0371257432797b4319c5829" // Must be set
    54  	cow.Greeting = "Moo!"
    55  	newRev, err := db.Put(context.TODO(), "cow", cow)
    56  	if err != nil {
    57  		panic(err)
    58  	}
    59  	cow.Rev = newRev
    60  }
    61  
    62  // As with updating a document, deletion depends on the proper _rev parameter.
    63  func ExampleDB_Delete() {
    64  	newRev, err := db.Delete(context.TODO(), "cow", "2-9c65296036141e575d32ba9c034dd3ee")
    65  	if err != nil {
    66  		panic(err)
    67  	}
    68  	fmt.Printf("The tombstone document has revision %s\n", newRev)
    69  }
    70  
    71  // When fetching a document, the document will be unmarshaled from JSON into
    72  // your structure by the row.ScanDoc method.
    73  func ExampleDB_Get() {
    74  	type Animal struct {
    75  		ID       string `json:"_id"`
    76  		Rev      string `json:"_rev,omitempty"`
    77  		Feet     int    `json:"feet"`
    78  		Greeting string `json:"greeting"`
    79  	}
    80  
    81  	var cow Animal
    82  	err := db.Get(context.TODO(), "cow").ScanDoc(&cow)
    83  	if err != nil {
    84  		panic(err)
    85  	}
    86  	fmt.Printf("The cow says '%s'\n", cow.Greeting)
    87  }
    88  
    89  // Design documents are treated identically to normal documents by both CouchDB
    90  // and Kivik. The only difference is the document ID.
    91  //
    92  // Store your document normally, formatted with your views (or other functions).
    93  func ExampleDB_Put_updateView() {
    94  	_, err := db.Put(context.TODO(), "_design/foo", map[string]interface{}{
    95  		"_id": "_design/foo",
    96  		"views": map[string]interface{}{
    97  			"foo_view": map[string]interface{}{
    98  				"map": "function(doc) { emit(doc._id) }",
    99  			},
   100  		},
   101  	})
   102  	if err != nil {
   103  		panic(err)
   104  	}
   105  }
   106  
   107  func ExampleDB_Query() {
   108  	rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Params(map[string]interface{}{
   109  		"startkey": `foo`,
   110  		"endkey":   `foo` + kivik.EndKeySuffix,
   111  	}))
   112  	defer rs.Close()
   113  	for rs.Next() {
   114  		var doc interface{}
   115  		if err := rs.ScanDoc(&doc); err != nil {
   116  			panic(err)
   117  		}
   118  		/* do something with doc */
   119  	}
   120  	if rs.Err() != nil {
   121  		panic(rs.Err())
   122  	}
   123  }
   124  
   125  func ExampleDB_Query_compoundKey() {
   126  	rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Params(map[string]interface{}{
   127  		"startkey": []string{"foo", "bar"},
   128  		"endkey":   []string{"foo", "bar" + kivik.EndKeySuffix},
   129  	}))
   130  	defer rs.Close()
   131  	for rs.Next() {
   132  		var doc interface{}
   133  		if err := rs.ScanDoc(&doc); err != nil {
   134  			panic(err)
   135  		}
   136  		/* do something with doc */
   137  	}
   138  	if rs.Err() != nil {
   139  		panic(rs.Err())
   140  	}
   141  }
   142  
   143  func ExampleDB_Query_literalJSONKeys() {
   144  	rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Param(
   145  		"startkey", json.RawMessage(`{"foo":true}`),
   146  	))
   147  	defer rs.Close()
   148  	for rs.Next() {
   149  		var doc interface{}
   150  		if err := rs.ScanDoc(&doc); err != nil {
   151  			panic(err)
   152  		}
   153  		/* do something with doc */
   154  	}
   155  	if rs.Err() != nil {
   156  		panic(rs.Err())
   157  	}
   158  }
   159  
   160  func ExampleDB_Query_multiple() {
   161  	rs := db.Query(context.TODO(), "_design/foo", "_view/bar", kivik.Param(
   162  		"queries", []interface{}{
   163  			map[string]interface{}{
   164  				"startkey":     []string{"foo", "bar"},
   165  				"endkey":       []string{"foo", "bar" + kivik.EndKeySuffix},
   166  				"include_docs": true,
   167  			},
   168  			map[string]interface{}{
   169  				"startkey":     []string{"baz", "bar"},
   170  				"endkey":       []string{"baz", "bar" + kivik.EndKeySuffix},
   171  				"include_docs": true,
   172  			},
   173  		}))
   174  	defer rs.Close()
   175  	var rsIndex int
   176  	for rs.NextResultSet() {
   177  		rsIndex++
   178  		for rs.Next() {
   179  			var doc interface{}
   180  			if err := rs.ScanDoc(&doc); err != nil {
   181  				panic(err)
   182  			}
   183  			/* do something with doc */
   184  		}
   185  	}
   186  }
   187  
   188  //nolint:revive // allow empty block in example
   189  func ExampleDB_Query_mapReduce() {
   190  	opts := kivik.Param("group", true)
   191  	rows := db.Query(context.TODO(), "_design/foo", "_view/bar", opts)
   192  	if err := rows.Err(); err != nil {
   193  		panic(err)
   194  	}
   195  	for rows.Next() {
   196  		/* ... */
   197  	}
   198  }
   199
View as plain text