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 driver 14 15 import ( 16 "encoding/json" 17 "io" 18 ) 19 20 // Row is a generic view result row. 21 type Row struct { 22 // ID is the document ID of the result. 23 ID string `json:"id"` 24 // Rev is the document revision. Typically only set when fetching a single 25 // document. 26 Rev string `json:"_rev"` 27 // Key is the view key of the result. For built-in views, this is the same 28 // as [ID]. 29 Key json.RawMessage `json:"key"` 30 // Value is an [io.Reader] to access the raw, un-decoded JSON value. 31 // For most built-in views, such as /_all_docs, this is `{"rev":"X-xxx"}`. 32 Value io.Reader `json:"-"` 33 // Doc is an [io.Reader] to access the raw, un-decoded JSON document. 34 // This is only populated by views which return docs, such as 35 // /_all_docs?include_docs=true. 36 Doc io.Reader `json:"-"` 37 // Attachments is an attachments iterator. Typically only set when fetching 38 // a single document. 39 Attachments Attachments `json:"-"` 40 // Error represents the error for any row not fetched. Usually just 41 // 'not_found'. 42 Error error `json:"-"` 43 } 44 45 // Rows is an iterator over a view's results. 46 type Rows interface { 47 // Next is called to populate row with the next row in the result set. 48 // 49 // Next should return [io.EOF] when there are no more rows, or [EOQ] after 50 // having reached the end of a query in a multi-query resultset. row should 51 // not be updated when an error is returned. 52 Next(row *Row) error 53 // Close closes the rows iterator. 54 Close() error 55 // UpdateSeq is the update sequence of the database, if requested in the 56 // result set. 57 UpdateSeq() string 58 // Offset is the offset where the result set starts. 59 Offset() int64 60 // TotalRows is the number of documents in the database/view. 61 TotalRows() int64 62 } 63 64 // RowsWarner is an optional interface that may be implemented by a [Rows], 65 // which allows a rows iterator to return a non-fatal warning. This is intended 66 // for use by the /_find endpoint, which generates warnings when indexes don't 67 // exist. 68 type RowsWarner interface { 69 // Warning returns the warning generated by the query, if any. 70 Warning() string 71 } 72 73 // Bookmarker is an optional interface that may be implemented by a [Rows] for 74 // returning a paging bookmark. 75 type Bookmarker interface { 76 // Bookmark returns an opaque bookmark string used for paging, added to 77 // the /_find endpoint in CouchDB 2.1.1. See the [CouchDB documentation] for 78 // usage. 79 // 80 // [CouchDB documentation]: http://docs.couchdb.org/en/2.1.1/api/database/find.html#pagination 81 Bookmark() string 82 } 83