Standardizing Our Drivers Through Specifications: A Look at the CRUD API
1 like1,434 views
The document discusses the standardization of MongoDB drivers through specifications aimed at improving consistency, behavior, and API documentation across various programming languages. It highlights the need to address variations in naming, semantics, and functionality, and presents a detailed overview of CRUD operations and their differences. Additionally, it outlines the goals for better developer productivity and framework support for third-party drivers.
![OtherReadMethods
aggregate(pipeline:Document[],options:AggregateOptions):
Iterable<Document>;
count(filter:Document,options:CountOptions):
Int64;
distinct(fieldName:string,filter:Document,options:DistinctOptions):
Iterable<any>;](https://image.slidesharecdn.com/8mdwxnuzsmel54lp60tg-signature-6890f3aacf562a90c013beaa54e3fbda5c663c02f354fba4adc6122a50eef114-poli-150605211550-lva1-app6892/85/Standardizing-Our-Drivers-Through-Specifications-A-Look-at-the-CRUD-API-31-320.jpg)
![BulkWrites
bulkWrite(requests:WriteModel[],options:BulkWriteOptions):
BulkWriteResult;
Remember initializeOrderedBulkOp(),
or the really old fluent API from 2013?](https://image.slidesharecdn.com/8mdwxnuzsmel54lp60tg-signature-6890f3aacf562a90c013beaa54e3fbda5c663c02f354fba4adc6122a50eef114-poli-150605211550-lva1-app6892/85/Standardizing-Our-Drivers-Through-Specifications-A-Look-at-the-CRUD-API-39-320.jpg)
Standardizing Our Drivers Through Specifications: A Look at the CRUD API
- 5. DriversToday APIs evolved over many years Idiomatic for their language Inconsistent with each other Subtle behavioral differences Our support team loves this!
- 6. Specifications Authentication SDAM, server selection Wire protocol, write commands User-facing APIs CRUD, enumeration, $out
- 7. EndGoals Consistency across drivers Behavior and API More intuitive documentation Increased developer productivity Guidance for third-party drivers
- 8. EndGoals(Continued) Mitigate Parkinson’s law of triviality
- 9. AvailableonGitHub Internal WIPs → Released Specs See: mongodb/specifications Mailing lists are still in vogue: andmongodb-drivers mongodb-dev
- 12. Whatareweaddressing? Collection-level read/write methods. Variations in naming and semantics. Inconsistent functionality and APIs.
- 18. CRUDCRADBOoMFaM Create Read Update Delete Count Replace Aggregate Distinct Bulk, One or Many Find and Modify
- 21. Terminology Collection: class or interface representing a collection. Spec defines methods to be implemented on this object. Iterable: some iterable object or structure. Cursor or cursor-like abstraction for reads. Vector or array for write method arguments.
- 22. Operations Methods to be implemented on the Collection object. These have required and optional parameters.
- 23. Deviations Spec is flexible with naming and option handling. This permits idiomaticity. (real word)☜
- 24. NamingDeviations “Root” words are non-negotiable. batchSize, batch_size ʕ•ᴥ•ʔ batchCount щ（ﾟДﾟщ） maxTimeMS, maxTime ͡° ͜ʖ ͡° maximumTime? (╯°□°）╯︵ ┻━┻ FindOptions, FindArgs (ﺡﾟヮﾟ)ﾉ QueryParams? (ノಠ益ಠ)ノ彡┻━┻ ordered, isOrdered ᕕ( ᐛ )ᕗ
- 25. OptionHandling Required options are positional arguments. For optional options, you have some options: Named parameters Dictionary or hash objects Option classes (e.g. UpdateOptions) May be consolidated, shared Fluent builders for find(), aggregate() Document when order of operations applies!
- 26. Whatwe’renotdoing Method overloading. Encapsulating params in “Model” classes. Codifying inconsistent APIs for BC.
- 28. Querying find(filter:Document,options:FindOptions): Iterable<Document>; filteris criteria (i.e. $querymeta operator). Support other operators through options. Iterable is obviously a cursor here.
- 29. FindOptions allowPartialResults: Boolean batchSize: Int32 comment: String cursorType: CursorType limit: Int32 maxTimeMS: Int64 modifiers: Document noCursorTimeout: Boolean oplogReplay: Boolean projection: Document skip: Int32 sort: Document
- 30. AbstractingInternalDetails CursorTypeenum may be normal, tailable, or tailable and awaitable. Today’s wire protocol flags are tomorrow’s command options. Users shouldn’t care and it’s not worth future API breaks.
- 32. AggregateOptions allowDiskUse: Boolean batchSize: Int32 maxTimeMS: Int64 useCursor: Boolean useCursordefault varies by server version. May affect the kind of Iterable returned.
- 34. WriteMethods insertOne(document:Document): InsertOneResult; insertMany(Iterable<Document>documents,options:InsertManyOptions): InsertManyResult; deleteOne(filter:Document): DeleteResult; deleteMany(filter:Document): DeleteResult; One or many behavior is explicit and facilitates self-documenting code. Eliminates inconsistency between multiand justOne defaults for update()and remove(), respectively.
- 35. insertMany() insertManyis syntactic sugar for bulkWrite()with inserts. Spec doesn’t address legacy batch OP_INSERToperations.
- 37. WriteMethods(Continued) replaceOne(filter:Document,replacement:Document,options:UpdateOptions): UpdateResult; updateOne(filter:Document,update:Document,options:UpdateOptions): UpdateResult; updateMany(filter:Document,update:Document,options:UpdateOptions): UpdateResult; Same points about explicit, self-documenting code apply. Trivial to validate if replacement or update documents contain operators.
- 39. BulkWrites bulkWrite(requests:WriteModel[],options:BulkWriteOptions): BulkWriteResult; Remember initializeOrderedBulkOp(), or the really old fluent API from 2013?
- 40. WriteModel Also, remember when we said we weren’t doing “model” classes that encapsulate all arguments?
- 41. WriteModel Models include required and optional (if any) arguments from single write methods. bulkWrite()’s requestsargument allows users to specify all of their writes at once and in a single method call. Trivial to make a fluent API atop this, although it’s not in the spec.
- 42. UpdateManyModel(f.e.) filter: Document required update: Document required upsert: Boolean optional
- 43. BulkWriteOptions ordered: Boolean Basically the same thing as InsertManyOptions.
- 44. ResultClasses Insert results may report driver-generated IDs Delete results include counts Update results include counts and server-generated IDs from upserts Bulk results aggregate all of the above Results are optional for unacknowledged writes. (e.g. Optional<BulkWriteResult>, isAcknowledgedboolean) Since all fields within insert results are optional, insertOne()and insertMany()may be void!
- 45. WriteErrors Spec is flexible on how errors are reported Mainly concerned that info is accessible under consistent fields and names. Doesn’t address merging errors We have a bulk write spec for that
- 47. FindandModifyMethods findOneAndDelete( filter:Document, options:FindOneAndDeleteOptions ):Document; findOneAndReplace( filter:Document, replacement:Document, options:FindOneAndReplaceOptions ):Document; findOneAndUpdate( filter:Document, update:Document, options:FindOneAndUpdateOptions ):Document; Option classes contain only the relevant command options.
- 48. PreemptiveQ&A
- 49. ReadPreferences? Generally, queries on same collection will use the same read preference. Spec assumes it’s set on client, database, or collection. Per-operation read preferences are permitted; the spec simply doesn’t define it.
- 50. WriteConcerns? Everything we just said about read preferences…
- 51. findOne()etal. Drivers are free to keep existing methods and add new ones, too. Please keep options and naming consistent.
- 52. Thanks!
- 53. FIN. Questions?