[GODRIVER-3012] Create a CRUD query filters helper Created: 11/Oct/23  Updated: 16/Oct/23

Status: Backlog
Project: Go Driver
Component/s: CRUD
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Unknown
Reporter: Matt Dale Assignee: Unassigned
Resolution: Unresolved Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by GODRIVER-3006 Deprecate Collection.UpdateByID Blocked
Related
is related to GODRIVER-2459 Proposal: Improve a way of making fil... Backlog
is related to GODRIVER-2999 Implemente ReplaceByID Closed
is related to GODRIVER-2889 Create aggregation pipeline helpers Backlog

 Description   

There are a number of CRUD APIs that accept a filter parameter, including:

Find
FindOne
FindOneAndUpdate
FindOneAndReplace
FindOneAndDelete
UpdateOne
UpdateMany
ReplaceOne
Distinct
DeleteOne
DeleteMany

Currently, most users define filters using bson.M or bson.D, which resembles the API used by mongosh. However, the syntax of bson.D can be extremely awkward (see GODRIVER-2271) and defining filters with bson.M requires users to know the proper filter structure and is subject to common field name typos (e.g. "_id").

A much better way to define filters would be using query filter helpers that inform users what filters are available and enforce the correct structure and field naming.

Proposed syntax

Example of finding user documents by name and age

users.Find(ctx, bson.M{"name": "Bob", "age": bson.M{"$gte", 18}})

would become

users.Find(ctx, filter.Eq("name", "Bob").GTE("age", 18))

Example of replacing a document using the default primary ID

coll.ReplaceOne(ctx, bson.M{"_id": id}, doc)

would become

coll.ReplaceOne(ctx, filter.ID(id), doc)

Example of updating a document by the primary ID (using the UpdateByID helper)

coll.UpdateByID(ctx, id, doc)

would become

coll.UpdateOne(ctx, filter.ID(id), doc)

Definition of done

  • Create a helper package/type that defines a set of the most commonly used query operators.
  • The helper must be able to be combined with other query filters defined as bson.D or bson.M (i.e. allow incrementally replacing query filters defined with bson.D/bson.M with helper calls without replacing the entire filter).
  • Update all documentation to use the filter helpers instead of bson.D/bson.M where possible.

Open questions:

  • Should the filter helper be a new package (e.g. filter.Eq), a builder type (e.g. mongo.Filter().Eq), or something else?
  • What query operators should we support (see a full list here)?
    • Should we only support comparison operators, or other operator types as well (e.g. logical operators, nested element operators, etc)?
  • Should the helper output bson.D or another type? It must be possible to mix helper output with other query filters defined using bson.D/bson.M.
  • How do we advertise the existence of the filter package, specifically as a replacement for using bson.M or bson.D to define filters?

Generated at Thu Feb 08 08:39:52 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.