5.1 Creating Documents

Once a collection has been created, it can store JSON documents. You store documents by passing a JSON data structure to the Collection.add() function. Some languages have direct support for JSON data, others have an equivalent syntax to represent that data. MySQL Connectors that implement X DevAPI aim to implement support for all JSON methods that are native to the Connectors' specific languages.

In addition, in some MySQL Connectors the generic DbDoc objects can be used. The most convenient way to create them is by calling the Collection.newDoc(). DbDoc is a data type to represent JSON documents and how it is implemented is not defined by X DevAPI. Languages implementing X DevAPI are free to follow an object-oriented approach with getter and setter methods, or use a C struct style with public members.

For strictly-typed languages it is possible to create class files based on the document structure definition of collections. MySQL Shell can be used to create those files.

Table 5.1 Different Types of Document Objects, Their Supported Languages, and Their Advantages

Document Objects	Supported languages	Advantages
Native JSON	Scripting languages (JavaScript, Python)	Easy to use
JSON equivalent syntax	C# (Anonymous Types, ExpandoObject)	Easy to use
DbDoc	All languages	Unified across languages
Generated Doc Classes	Strictly typed languages (C#)	Natural to use

The following example shows the different methods of inserting documents into a collection.

MySQL Shell JavaScript Code

// Create a new collection 'my_collection'
var myColl = db.createCollection('my_collection');

// Insert JSON data directly
myColl.add({_id: '8901', name: 'Mats', age: 21}).execute();

// Inserting several docs at once
myColl.add([ {_id: '8902', name: 'Lotte', age: 24},
  {_id: '8903', name: 'Vera', age: 39} ]).execute();

MySQL Shell Python Code

// Create a new collection 'my_collection'
var myColl = db.createCollection('my_collection');

// Insert JSON data directly
myColl.add({_id: '8901', name: 'Mats', age: 21}).execute();

// Inserting several docs at once
myColl.add([ {_id: '8902', name: 'Lotte', age: 24},
  {_id: '8903', name: 'Vera', age: 39} ]).execute();

Node.js JavaScript Code

// Create a new collection 'my_collection'
db.createCollection('my_collection').then(function (myColl) {

  // Add a document to insert
  var insert = myColl.add({ name: 'Mats', age: 21 });

  // Add multiple documents to insert
  insert.add([
    { name: 'Lotte', age: 24 },
    { name: 'Vera', age: 39 }
  ]);

  // Add one more document to insert
  var myDoc = {};
  myDoc.name = 'Jamie';
  myDoc.age = 47;
  insert.add(myDoc);

  // run the operation
  return insert.execute();
});

C# Code

// Create a new collection "my_collection"
var myColl = db.CreateCollection("my_collection");

// Insert JSON data directly
myColl.Add(new { name = "Mats", age = 21 }).Execute();

// Inserting several docs at once
myColl.Add(new[] {new { name = "Lotte", age = 24},
new { name = "Vera", age = 39} }).Execute();

// Insert Documents using DbDoc
var myDoc = new DbDoc();
myDoc.SetValue("name", "Jamie");
myDoc.SetValue("age", 47);
myColl.Add(myDoc).Execute();

//Fetch all docs
var docResult = myColl.Find().Execute();
var docs = docResult.FetchAll();

Python Code

# Create a new collection 'my_collection'
my_coll = my_schema.create_collection('my_collection')

# Insert JSON data directly
my_coll.add({'name': 'Mats', 'age': 21}).execute()

# Inserting several docs at once
my_coll.add([
    {'name': 'Lotte', 'age': 24},
    {'name': 'Vera', 'age': 39}
]).execute()

Java Code

// Create a new collection 'my_collection'
Collection coll = db.createCollection("my_collection");

// Insert JSON data directly
coll.add("{\"name\":\"Mats\", \"age\":21}").execute();

// Insert several documents at once
coll.add("{\"name\":\"Lotte\", \"age\":24}",
        "{\"name\":\"Vera\", \"age\":39}").execute();

// Insert Documents using DbDoc
DbDoc myDoc = new coll.newDoc();

myDoc.add("name", new JsonString().setValue("Jamie"));
myDoc.add("age", new JsonNumber().setValue("47"));
coll.add(myDoc).execute();

C++ Code

// Create a new collection 'my_collection'
Collection myColl = db.createCollection("my_collection");

// Insert JSON data directly
myColl.add(R"({"name": "Mats", "age": 21})").execute();

// Inserting several docs at once
std::list<DbDoc> docs = {
  DbDoc(R"({"name": "Lotte", "age": 24})"),
  DbDoc(R"({"name": "Vera", "age": 39})")
};
myColl.add(docs).execute();