Over the past year, MongoDB's driver team has prioritized publishing specifications for essential driver functionality. In doing so, we hope to improve consistency and collaboration between our internal and community drivers. This session will look at our CRUD specification, which defines an API for querying, aggregation, and write operations: something that every MongoDB developer will interact with at some point. We'll also discuss the challenges in devising a single API that must be applicable to dozens of programming languages.

1. STANDARDIZINGOURDRIVERSTHROUGHSPECS:
ALOOKATTHECRUDAPI
OPENINGTUESDAY,JUNE2ND
INSELECTCONFERENCEROOMS.
Jeremy Mikola
jmikola

2. What’sthedealwithspecs?

3. ACursoryIntroduction
SHAMELESSLYBORROWEDFROM…

4. MongoDBhasalotofdrivers…

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

10. CRUDSpecification

12. Whatareweaddressing?
Collection-level read/write methods.
Variations in naming and semantics.
Inconsistent functionality and APIs.

13. DefaultBehaviors(ExhibitA)
//Updatesonedocument
db.things.update(
{"type":"human"},
{"$set":{"organic":true}}
);
//Removesallmatchingdocuments
db.things.remove(
{"type":"robot"}
);

14. OptionNames(ExhibitB)
//Updatesalldocuments
db.things.update(
{"type":"human"},
{"$set":{"organic":true}}
{"multi":true}
);
//Removesonematchingdocument
db.things.remove(
{"type":"robot"},
{"justOne":true}
);

15. MethodSignatures(ExhibitC)
//Accordingtothedocumentation
function(query,update,options){
//...
}
//Actualimplementation
function(query,update,upsert,multi){
if(typeof(upsert)==="object"){
//Unpackoptions...
}
//...
}
Legacy baggage with update()

16. CRUD
Create
Read
Update
Delete
insert()
find()
update()
remove()

17. ButWait…There’sMore!

18. CRUDCRADBOoMFaM
Create
Read
Update
Delete
Count
Replace
Aggregate
Distinct
Bulk, One or Many
Find and Modify

20. Ourentirelyreasonableand
level-headedapproach…
BEARWITHME.

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.

27. DivingintotheAPI
Chapter1:Reads

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.

31. OtherReadMethods
aggregate(pipeline:Document[],options:AggregateOptions):
Iterable<Document>;
count(filter:Document,options:CountOptions):
Int64;
distinct(fieldName:string,filter:Document,options:DistinctOptions):
Iterable<any>;

32. AggregateOptions
allowDiskUse: Boolean
batchSize: Int32
maxTimeMS: Int64
useCursor: Boolean
useCursordefault varies by server version.
May affect the kind of Iterable returned.

33. DivingintotheAPI
Chapter2:Writes
We’rebasically50%doneatthispoint…

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.

36. InsertManyOptions
ordered: Boolean

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.

38. UpdateOptions
upsert: Boolean

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

46. DivingintotheAPI
Chapter3:FindandModify
I’llkeepthisshort…

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?

54. ImageCredits
and
http://www.instructables.com/id/Egg-Cream/
Giphy Reaction Gifs
https://octodex.github.com/wheres-waldocat/