Standardizing Our Drivers Through Specifications: A Look at the CRUD API
-
Upload
mongodb -
Category
Technology
-
view
145 -
download
0
Transcript of Standardizing Our Drivers Through Specifications: A Look at the CRUD API
![Page 1: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/1.jpg)
STANDARDIZING OUR DRIVERS THROUGH SPECS:
A LOOK AT THE CRUD APIOPENING TUESDAY, JUNE 2ND
IN SELECT CONFERENCE ROOMS.
Jeremy Mikolajmikola
![Page 2: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/2.jpg)
What’s the deal with specs?
![Page 3: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/3.jpg)
A Cursory IntroductionSHAMELESSLY BORROWED FROM…
![Page 4: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/4.jpg)
MongoDB has a lot of drivers…
![Page 5: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/5.jpg)
Drivers Today
APIs evolved over many yearsIdiomatic for their languageInconsistent with each otherSubtle behavioral differences
Our support team loves this!
![Page 6: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/6.jpg)
Specifications
AuthenticationSDAM, server selectionWire protocol, write commandsUser-facing APIs
CRUD, enumeration, $out
![Page 7: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/7.jpg)
End Goals
Consistency across driversBehavior and API
More intuitive documentationIncreased developer productivityGuidance for third-party drivers
![Page 8: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/8.jpg)
End Goals (Continued)
Mitigate Parkinson’s law of triviality
![Page 9: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/9.jpg)
Available on GitHub
Internal WIPs → Released SpecsSee: mongodb/specifications
Mailing lists are still in vogue: and mongodb-drivers mongodb-dev
![Page 10: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/10.jpg)
CRUD Specification
![Page 11: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/11.jpg)
![Page 12: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/12.jpg)
What are we addressing?
Collection-level read/write methods.
Variations in naming and semantics.
Inconsistent functionality and APIs.
![Page 13: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/13.jpg)
Default Behaviors (Exhibit A)
// Updates one documentdb.things.update( { "type": "human" }, { "$set": { "organic": true } });
// Removes all matching documentsdb.things.remove( { "type": "robot" });
![Page 14: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/14.jpg)
Option Names (Exhibit B)
// Updates all documentsdb.things.update( { "type": "human" }, { "$set": { "organic": true } } { "multi": true });
// Removes one matching documentdb.things.remove( { "type": "robot" }, { "justOne": true });
![Page 15: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/15.jpg)
Method Signatures (Exhibit C)
// According to the documentationfunction (query, update, options) { // ...}
// Actual implementationfunction (query, update, upsert, multi) { if ( typeof(upsert) === "object" ) { // Unpack options... }
// ...}
Legacy baggage with update()
![Page 16: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/16.jpg)
CRUD
CreateReadUpdateDelete
insert()find()
update()remove()
![Page 17: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/17.jpg)
But Wait… There’s More!
![Page 18: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/18.jpg)
CRUDCRADBOoMFaM
CreateReadUpdateDeleteCountReplaceAggregateDistinctBulk, One or ManyFind and Modify
![Page 19: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/19.jpg)
![Page 20: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/20.jpg)
Our entirely reasonable andlevel-headed approach…
BEAR WITH ME.
![Page 21: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/21.jpg)
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.
![Page 22: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/22.jpg)
Operations
Methods to be implemented on the Collection object.
These have required and optional parameters.
![Page 23: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/23.jpg)
Deviations
Spec is flexible with naming and option handling.
This permits idiomaticity. (real word)☜
![Page 24: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/24.jpg)
Naming Deviations
“Root” words are non-negotiable.
batchSize, batch_size ʕ•ᴥ•ʔbatchCount щ(゚Д゚щ)
maxTimeMS, maxTime °͡ ʖ͜ °͡maximumTime? (╯°□°)╯︵ ┻━┻
FindOptions, FindArgs ح(゚ヮ゚)ノQueryParams? (ノಠ益ಠ)ノ彡┻━┻
ordered, isOrdered ᕕ( ᐛ )ᕗ
![Page 25: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/25.jpg)
Option Handling
Required options are positional arguments.
For optional options, you have some options:
Named parametersDictionary or hash objectsOption classes (e.g. UpdateOptions)
May be consolidated, sharedFluent builders for find(), aggregate()
Document when order of operations applies!
![Page 26: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/26.jpg)
What we’re not doing
Method overloading.
Encapsulating params in “Model” classes.
Codifying inconsistent APIs for BC.
![Page 27: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/27.jpg)
Diving into the API
Chapter 1: Reads
![Page 28: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/28.jpg)
Queryingfind(filter: Document, options: FindOptions): Iterable<Document>;
filter is criteria (i.e. $query meta operator).
Support other operators through options.
Iterable is obviously a cursor here.
![Page 29: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/29.jpg)
FindOptions
allowPartialResults: BooleanbatchSize: Int32comment: StringcursorType: CursorTypelimit: Int32maxTimeMS: Int64modifiers: DocumentnoCursorTimeout: BooleanoplogReplay: Booleanprojection: Documentskip: Int32sort: Document
![Page 30: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/30.jpg)
Abstracting Internal Details
CursorType enum may be normal,tailable, or tailable and awaitable.
Today’s wire protocol flags aretomorrow’s command options.
Users shouldn’t care andit’s not worth future API breaks.
![Page 31: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/31.jpg)
Other Read Methodsaggregate(pipeline: Document[], options: AggregateOptions): Iterable<Document>;
count(filter: Document, options: CountOptions): Int64;
distinct(fieldName: string, filter: Document, options: DistinctOptions): Iterable<any>;
![Page 32: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/32.jpg)
AggregateOptions
allowDiskUse: BooleanbatchSize: Int32maxTimeMS: Int64useCursor: Boolean
useCursor default varies by server version.
May affect the kind of Iterable returned.
![Page 33: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/33.jpg)
Diving into the API
Chapter 2: Writes
We’re basically 50% done at this point…
![Page 34: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/34.jpg)
Write MethodsinsertOne(document: Document): InsertOneResult;
insertMany(Iterable<Document> documents, options: InsertManyOptions): InsertManyResult;
deleteOne(filter: Document): DeleteResult;
deleteMany(filter: Document): DeleteResult;
One or many behavior is explicit andfacilitates self-documenting code.
Eliminates inconsistency between multi and justOnedefaults for update() and remove(), respectively.
![Page 35: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/35.jpg)
insertMany()
insertMany is syntactic sugarfor bulkWrite() with inserts.
Spec doesn’t address legacybatch OP_INSERT operations.
![Page 36: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/36.jpg)
InsertManyOptions
ordered: Boolean
![Page 37: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/37.jpg)
Write Methods (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 orupdate documents contain operators.
![Page 38: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/38.jpg)
UpdateOptions
upsert: Boolean
![Page 39: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/39.jpg)
Bulk WritesbulkWrite(requests: WriteModel[], options: BulkWriteOptions): BulkWriteResult;
Remember initializeOrderedBulkOp(),or the really old fluent API from 2013?
![Page 40: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/40.jpg)
WriteModel
Also, remember when we said we weren’t doing“model” classes that encapsulate all arguments?
![Page 41: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/41.jpg)
WriteModel
Models include required and optional (if any)arguments from single write methods.
bulkWrite()’s requests argumentallows 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.
![Page 42: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/42.jpg)
UpdateManyModel (f.e.)
filter: Document requiredupdate: Document requiredupsert: Boolean optional
![Page 43: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/43.jpg)
BulkWriteOptions
ordered: Boolean
Basically the same thing as InsertManyOptions.
![Page 44: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/44.jpg)
Result Classes
Insert results may report driver-generated IDsDelete results include countsUpdate results include counts andserver-generated IDs from upsertsBulk results aggregate all of the above
Results are optional for unacknowledged writes.(e.g. Optional<BulkWriteResult>, isAcknowledged boolean)
Since all fields within insert results are optional,insertOne() and insertMany() may be void!
![Page 45: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/45.jpg)
Write Errors
Spec is flexible on how errors are reportedMainly concerned that info is accessibleunder consistent fields and names.Doesn’t address merging errors
We have a bulk write spec for that
![Page 46: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/46.jpg)
Diving into the API
Chapter 3: Find and Modify
I’ll keep this short…
![Page 47: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/47.jpg)
Find and Modify MethodsfindOneAndDelete( filter: Document, options: FindOneAndDeleteOptions): Document;
findOneAndReplace( filter: Document, replacement: Document, options: FindOneAndReplaceOptions): Document;
findOneAndUpdate( filter: Document, update: Document, options: FindOneAndUpdateOptions): Document;
Option classes contain onlythe relevant command options.
![Page 48: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/48.jpg)
Preemptive Q&A
![Page 49: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/49.jpg)
Read Preferences?
Generally, queries on same collectionwill use the same read preference.
Spec assumes it’s set onclient, database, or collection.
Per-operation read preferences are permitted;the spec simply doesn’t define it.
![Page 50: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/50.jpg)
Write Concerns?
Everything we just said about read preferences…
![Page 51: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/51.jpg)
findOne() et al.
Drivers are free to keep existing methodsand add new ones, too.
Please keep options and naming consistent.
![Page 52: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/52.jpg)
Thanks!
![Page 53: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/53.jpg)
FIN.
Questions?
![Page 54: Standardizing Our Drivers Through Specifications: A Look at the CRUD API](https://reader030.fdocuments.in/reader030/viewer/2022032618/55b38cc4bb61eb4e748b4717/html5/thumbnails/54.jpg)
Image Credits
and http://www.instructables.com/id/Egg-Cream/Giphy Reaction Gifshttps://octodex.github.com/wheres-waldocat/