A newer version of this documentation is available.

View Latest

Data Modeling Basics

    Couchbase Server is a multi-model database that natively manipulates data in key-value form or in JSON documents. Unlike relational databases which require strict predefined schema with tables and columns, Couchbase Server requires no predefined schema. Each JSON document represents its own schema and can specify its own set of attributes per document.

    With Couchbase Server, applications can define their schema at the application layer and freely evolve their schema with no added administrative action. Schema changes do not require scheduling downtime nor do they trigger long running, offline updates to existing data.

    Couchbase Server supports both document and key-value data natively. Document-based data representation allows complex objects to be natively represented with full fidelity in Couchbase Server. Key-value representation can be mixed with document-centric design and is typically used to optimize access for extreme low latencies.

    Relational Data Modeling vs Document Oriented Data Modeling

    In a relational database system you must define a schema before adding records to a database. The schema is the structure described in a formal language supported by the database and provides a blueprint for the tables in a database and the relationships between tables of data. Within a table, you need to define constraints in terms of rows and named columns as well as the type of data that can be stored in each column.

    In contrast, a document-oriented database contains documents, which are records that describe the "schema" of the data in the document, as well as the actual data. Documents can be as complex as you choose; you can use nested data to provide additional sub-categories of information about your object. You can also use one or more documents to represent a real-world object.

    Using JSON Documents

    JavaScript Object Notation (JSON) is a lightweight data-interchange format which is easy to read and change. JSON is language-independent although it uses similar constructs to JavaScript. JSON documents enable you to benefit from all new Couchbase features, such as indexing and querying; they also to provide a logical structure for more complex data and enable you to provide logical connections between different records.

    JSON supports the following basic data types:

    • Numbers, including integer and floating point

    • Strings, including all unicode characters and backslash escape characters

    • Boolean: true or false

    • Arrays, enclosed in square brackets: ["one", "two", "three"]

    • Objects, consisting of key-value pairs, and also known as an associative array or hash. The key must be a string and the value can be any supported JSON data type.

    For more information on creating valid JSON documents, see http://www.json.org.

    When you use JSON documents to represent your application data, you should think about the document as a logical container for information. This involves thinking about how data from your application fits into natural groups. It also requires thinking about the information you want to manage in your application. Data modeling for Couchbase Server is similar to the process that you would follow for traditional relational databases; however, there is much more flexibility and you can change your data structures later on.

    A sample entity may be a "hotel" you represent for a travel web site that provides information on many hotels. The "hotel" entity may contain many attributes such as name and address, and may contain embedded structured like reviews that can represent individual reviews users have submitted for a given hotel.

       "address":"Capstone Road, ME7 3JE",
       "country":"United Kingdom",
       "hotel_name":"Medway Youth Hostel",
             "content":"This was our 2nd trip here and we enjoyed it as much or more than last year. ",
             "date":"2013-06-22 18:33:50 +0300",
             "content":"We found the hotel de la Monnaie through Interval and we thought we'd give it a try while we attended a conference in New Orleans. This place was a perfect location and it definitely beat staying downtown at the Hilton with the rest of the attendees",
             "date":"2015-03-02 19:56:13 +0300",
                "Business service (e.g., internet access)":4,
                "Check in / front desk":4,

    In traditional relational database modeling, you would create tables that contain a subset of information for an entity. Just like the example above, a hotel may contain many reviews which are stored in a separate table and referenced by the hotel_id. In case of JSON documents, you use key-values pairs, or even nested key-value pairs and don’t have to break "hotels" and "hotel reviews" apart.

    Given the boundary-less nature of the document model, there are several considerations to have in mind when you design your JSON document:

    • Whether you want to use a type field at the highest level of your JSON document in order to group and filter object types, for instance the above example includes a "type" attribute that has the value "hotel".

    • What particular keys, ids, prefixes or conventions do you want to use for items, for instance ‘Hotel::Medway_Youth_Hostel.’

    • If want to use a document to access other documents. In other words, you can store keys that refer other documents in a JSON document and get the keys through this document. For instance, the above example includes author_id under reviews that refer to the detailed information on authors.