I'm having a hard time understanding TinyDB's storage format.

[ezxpro]

I'd like someone to give me a basic explanation of how TinyDB stores data and how it is represented in the JSON it creates. Basically, I'd like to know how it represents a database, a table, a row and an entry inside the JSON

I read the Getting Started and skimmed through the Asvanced usage sections the documentation, but still have doubts,

That because I inserted some entries into a database using db.insert(). However, when check the JSON file, I have something like this:

{"_default": {"1": {"animal": "dog", "fruits": "apple", "object": "knife"}, "2": {"animal": "dog", "fruit": "apple", "vegetable": "lettuce", "object": "pen"}, "3": {"medicine": "aspirin", "profession": "mason", "candy": "chocolate"}, "4": {"car": "Mazda Miata"}, "5": {"primate": "orangutan"}, "6": {"count": "5"}, "7": {"count": 11}}}

As you can see, stuff is nested, and I don't know what is the name of the database (I'm supposing it's "_default", what is a table, what is a row and how exactly it decides to nest the entries.

[msiemens]

Basically, tables are represented like this:

{
  "table_name": {
    "document_id": {
      "your": "document"
    }
  }
}

The default table's name is _default, so that's what you see in your example. Every table is a JSON object where the key is the document ID and the value is the document itself. This allows to look up documents by their ID without having to run through a list of documents to find the right one.

Originally (before v2.0), TinyDB used lists to store documents, but that way looking up a document by ID was really slow for large tables. That's where using the document ID as a key comes from.

As a last note: In JSON all object keys MUST be strings, so every document ID will be stored as a string regardless of its Python type. That's why TinyDB has to convert the document ID back to its original type when reading data, see for example

tinydb/tinydb/table.py

Lines 249 to 256 in 6307a9f

	# Perform the search by applying the query to all documents.
	# Then, only if the document matches the query, convert it
	# to the document class and document ID class.
	docs = [
	self.document_class(doc, self.document_id_class(doc_id))
	for doc_id, doc in self._read_table().items()
	if cond(doc)
	]