Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 22 additions & 5 deletions docs/mongodb.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,11 +99,28 @@ estimate of a whole collection, run the `count` command with `DB.Command`.

## Commands

`DB.Command` runs any command in the database and returns its reply. A reply with
`ok: 0`, `writeErrors` or a `writeConcernError` comes back together with a
`*CommandError` holding its code, code name and message. `DB.Cursor` runs a
command that opens a cursor, such as `aggregate` or `listIndexes`, and yields its
documents the way `Find` does.
`DB.Command` runs any command in the database and returns its reply. Put the
command name first in an ordered document such as `bson.D` or `bson.Raw`.
Multi-key maps without a custom BSON encoder, including ordinary `bson.M`, are
rejected before sending because MongoDB uses the first key to identify the
command. Custom `bson.Marshaler` implementations remain supported and are
responsible for emitting an ordered command. Maps nested in a command's filter
or other arguments are unaffected; single-key commands such as
`bson.M{"ping": 1}` are also accepted.

A reply with `ok: 0`, `writeErrors` or a `writeConcernError` comes back together
with a `*CommandError` holding its code, code name and message. `DB.Cursor` takes
an ordered command that opens a cursor, such as `aggregate` or `listIndexes`,
and yields its documents the way `Find` does. Its `getMore` and cleanup commands
repeat an explicit `lsid`, `apiVersion`, `apiStrict` and `apiDeprecationErrors`
from the opening command. Within a multi-document transaction, marked by
`autocommit: false`, they also repeat `txnNumber` and `autocommit`, but not
`startTransaction`. The `txnNumber` of a retryable write, such as `bulkWrite`,
is not repeated, as MongoDB accepts it only on the write itself. Each `getMore`
also repeats a positive batch size, from `batchSize` for `find` or
`cursor.batchSize` for `aggregate` and the list commands, so later batches stay
as small as the first. The cursor is cleaned up if the loop exits early,
returns an error or panics, even after the caller's context is canceled.

```go
create := bson.D{{Key: "create", Value: "users"}}
Expand Down
31 changes: 31 additions & 0 deletions docs/search.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,36 @@ if len(hits) > 0 {
}
```

A successful HTTP status does not guarantee a complete search. If the backend
reports `timed_out: true`, `_shards.failed > 0`, or, for a cross-cluster search,
a nonzero `_clusters.skipped`, `_clusters.partial` or `_clusters.failed`,
`Search` returns a `*search.PartialResponseError` **and any decoded hits**. A
remote cluster skipped under `skip_unavailable` is reported this way. An empty
hit slice in this case does not mean there were no matches. A caller requiring
complete results must reject these hits; a best-effort caller may explicitly
choose to use them after inspecting the error with `errors.As`:

```go
hits, err := products.Search(ctx, query)
if err != nil {
var partial *search.PartialResponseError
if !errors.As(err, &partial) { return err }
// This caller accepts incomplete results; hits may still be empty.
log.Printf("partial search: timed_out=%t failed_shards=%d", partial.TimedOut, partial.FailedShards)
}
```

`TimedOut` and `FailedShards` report the backend's completion metadata.
`ShardFailures` holds each `_shards.failures` entry as `json.RawMessage`,
preserving its shard, index and backend-specific reason details. The backend
may omit these entries even when `FailedShards` is nonzero. `SkippedClusters`,
`PartialClusters` and `FailedClusters` report the `_clusters` counts and are
zero for a search of one cluster. This error does not trigger an automatic
retry. Complete responses still return hits and a nil error; HTTP status and
JSON decoding errors retain their existing behavior. A successful response
without a `hits.hits` array, such as `{}`, is a decoding error rather than an
empty result.

## HTTP requests

`Index.Do` sends any HTTP request with a path relative to the index, such as
Expand Down Expand Up @@ -113,6 +143,7 @@ as it is for a search.
| `*weir.Error` | A record failed. `weir.CodeOf(err)` gives its `FailureCode`, and `Outcome` tells whether a write applied. |
| `weir.ErrInterrupted` | An outage cut the request short, so it may succeed later. It may have run: never send a write again without checking. |
| `*search.StatusError` | `Search` got a status of 300 or more |
| `*search.PartialResponseError` | `Search` timed out, had failed shards or did not search every cluster despite a successful HTTP status. Any returned hits may be incomplete. |

A write certainly took no effect only when its `*weir.Error` has the `Outcome`
`MutationNotStarted` or `MutationNotApplied`, or, for a request, the
Expand Down
Loading