Collections are a new feature in Couchbase 6.5. They let you group similar documents within each bucket, just as tables in relational databases collect similar records within each database. Collections will be fully supported in Couchbase 7.0, but you can try them right now in the Couchbase 6.5 release as a Developer Preview feature. The Demo Application already uses them.<\/p>\n
What Are Collections?<\/strong> In older versions of Couchbase, data was organized like this:<\/p>\n In Couchbase 6.5, there are two more layers, like this:<\/p>\n How Are Collections Useful?<\/b><\/p>\n Collections are the lowest level of document organization, and directly contain documents. They are useful because they let you group documents more precisely than was possible before. Rather than dumping all different types of documents (products, orders, customers) into a single bucket and distinguishing them by a type field, you can instead create a collection for each type. And when you query, you can query against the collection, not just the whole bucket. You will also eventually be able to control access at the collection level.<\/p>\n Scopes are the level of organization above collections. Scopes contain collections and collections contain documents. There are different ways to use scopes, depending on what the Couchbase cluster is being used for. If it is supporting many different internal applications for a company, each application should have a scope of its own. If the cluster is being used to serve many client organizations, each running its own copy of an application, each copy should have a scope of its own. Similarly, if a cluster is being used by dev groups, perhaps for testing, the unit of allocation should be a scope. In each case, the owner can then create whatever collections they want under the scope they are assigned.<\/p>\n Scopes have to be unique within their buckets, and collections have to be unique within their scopes. Accordingly, the “default” bucket could contain two scopes “dev” and “prod”, each with their own “products” and “customers” collections.<\/p>\n Use of Collections<\/b><\/p>\n You can see collections and scopes being used in the latest version of the Couchbase Demo Application, here:<\/p>\n https:\/\/github.com\/couchbaselabs\/try-cb-java\/tree\/6.5.0-branch<\/a><\/p>\n This application uses an existing “travel-sample” bucket as is to let the user search for flights and hotels, but stores its own user and bookings data in collections. The structure being used is this:<\/p>\n When the user creates an account, a document is created in the “users” collection. When they book flights, documents are created in the “flights” collection, and referenced in the user’s document in the “users” collection.<\/p>\n This design allows multiple applications to share the same bucket. If we had a second instance of the demo app, used by another travel agency, we could just create another scope (with its own “users” and “flights” collections,) and point the second instance at this scope by updating its application.properties file. The two instances would operate side by side, without interfering with each other.<\/p>\n Example Code<\/b><\/p>\n To begin with, the bucket and scope that contain user and bookings information are named in the application.properties file:<\/p>\n These configuration values are picked up in the Database.java file:<\/p>\n In User.java, we see how a new flight is registered for the user. The scope bean, created above, is passed in. The username is the id the name the user logged in with.<\/p>\n The id of the user document is the username of the user. The application knows to get it from the “users” collection, in the collection used by the application.<\/p>\n The flights the user has booked are stored in the user document, in an array named “flights”.<\/p>\n We add the new flights to the existing flights.<\/p>\n Then we store the new version of the user document.<\/p>\n Just below, we see how the flights of a user are retrieved.<\/p>\n Get the user document from the “users” collection.<\/p>\n Get the “flights” array from the user document. It contains a list of flight ids.<\/p>\n Retrieve each flight document from the “flights” collection” by ID.<\/p>\n Changes From Earlier Code<\/b><\/p>\n The code for working with users and their flights was quite different in the previous version, which didn’t use collections. There, booked flights were stored directly in the user document. The user document was stored directly in the “travel-sample” table. Here is the original code for the registerFlightForUser() function.<\/p>\n Notice the use of a prefix to mark the type of document. This isn’t necessary once collections are available.<\/p>\n We retrieve the array of flights, which is already in the document.<\/p>\n We add the flights to the array of booked flights.<\/p>\n And we store the user document.<\/p>\n Obviously, separating the booked flights from the user isn’t terribly compelling in a toy application. But in a production application, where we are storing many types of information of information about each user, it would make sense to store some records outside the user document, particularly any that were large or numerous or prone to changing frequently.<\/p>\n Scopes and Collections Documentation<\/b><\/p>\n To find out more about how to work with scopes and collection directly, consult this documentation<\/a>, which explains the RESTful API for working with both, the relevant CLI commands, and information about collections available from cbstats<\/em>.<\/p>\n Summary<\/b><\/p>\n Collections and scopes let you organize documents within a Couchbase bucket, just as tables and schemas let you organized rows within relational databases. The current Couchbase 6.5 GA release provides early, limited support for collections and scopes as a Developer Preview feature. To get started with collections and scopes, you can start working with the Java Demo Application right now.<\/p>\n Download<\/i><\/p>\n Download Couchbase Server 6.5<\/a><\/span><\/p>\n \u00a0<\/i>Documentation<\/i><\/p>\n Couchbase Collections 6.5 Documentation<\/a><\/p>\n Couchbase Server 6.5 Release Notes<\/a><\/span><\/p>\n Couchbase Server 6.5 What\u2019s New<\/a><\/span><\/p>\n Blogs<\/i><\/p>\n Introducing Collections – Developer Preview in Couchbase Server 6.5<\/a><\/p>\n Announcing Couchbase Server 6.5 \u2013 What\u2019s New and Improved<\/a><\/span><\/p>\n
\nIf you are coming from the world of relational databases, you can think of collections as tables. All the documents within a couchbase collection should be of the same type, just as all the records in a relational table are of the same type. There might be a “customer” table or a “product” table in a relational schema; similarly, there might be a “customer” collection in a Couchbase bucket.<\/p>\n\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
\n
storage.clientorg.bucket=default\r\nstorage.clientorg.scope=larson-travel<\/pre>\n
@Configuration\r\npublic class Database {\r\n\r\n ...\r\n\r\n @Value(\"${storage.clientorg.bucket}\")\r\n private String clientOrgBucket;\r\n\r\n @Value(\"${storage.clientorg.scope}\")\r\n private String clientOrgScope;\r\n\r\n ...\r\n\r\n public Bucket clientOrgBucket() {\r\n return loginCluster().bucket(clientOrgBucket);\r\n }\r\n\r\n public @Bean Scope clientOrgScope() {\r\n return clientOrgBucket().scope(clientOrgScope);\r\n }\r\n\r\n}\r\n<\/pre>\n public Result<Map<String, Object>> registerFlightForUser(final Scope scope, \r\n final String username, final JsonArray newFlights) {\r\n<\/pre>\n String userId = username;\r\n Collection usersCollection = scope.collection(USERS_COLLECTION_NAME);\r\n Collection flightsCollection = scope.collection(FLIGHTS_COLLECTION_NAME);\r\n Optional<GetResult> userDataFetch = usersCollection.get(userId);\r\n if (!userDataFetch.isPresent()) {\r\n throw new IllegalStateException();\r\n }\r\n JsonObject userData = userDataFetch.get().contentAsObject();\r\n\r\n if (newFlights == null) {\r\n throw new IllegalArgumentException(\"No flights in payload\");\r\n }\r\n\r\n JsonArray added = JsonArray.empty();\r\n<\/pre>\n JsonArray allBookedFlights = userData.getArray(\"flights\");\r\n if(allBookedFlights == null) {\r\n allBookedFlights = JsonArray.create();\r\n }\r\n<\/pre>\n for (Object newFlight : newFlights) {\r\n checkFlight(newFlight);\r\n JsonObject t = ((JsonObject) newFlight);\r\n t.put(\"bookedon\", \"try-cb-java\");\r\n String flightId = UUID.randomUUID().toString();\r\n flightsCollection.insert(flightId, t);\r\n allBookedFlights.add(flightId);\r\n added.add(t);\r\n }\r\n\r\n userData.put(\"flights\", allBookedFlights);\r\n<\/pre>\n usersCollection.upsert(userId, userData);\r\n\r\n JsonObject responseData = JsonObject.create()\r\n .put(\"added\", added);\r\n\r\n return Result.of(responseData.toMap(), \r\n \"Booked flight in Couchbase document \" + userId);\r\n }\r\n<\/pre>\n
public List<Map<String, Object>> getFlightsForUser(final Scope scope, \r\n final String username) {\r\n<\/pre>\n Collection users = scope.collection(USERS_COLLECTION_NAME);\r\n Optional<GetResult> doc = users.get(username);\r\n if (!doc.isPresent()) {\r\n return Collections.emptyList();\r\n }\r\n JsonObject data = doc.get().contentAsObject();\r\n<\/pre>\n JsonArray flights = data.getArray(\"flights\");\r\n if (flights == null) {\r\n return Collections.emptyList();\r\n }\r\n<\/pre>\n \/\/ The \"flights\" array contains flight ids. Convert them to actual objects.\r\n Collection flightsCollection = scope.collection(FLIGHTS_COLLECTION_NAME);\r\n List<Map<String, Object>> results = new ArrayList<Map<String, Object>>();\r\n for (int i = 0; i < flights.size(); i++) {\r\n String flightId = flights.getString(i);\r\n Optional<GetResult> res = flightsCollection.get(flightId);\r\n if (!res.isPresent()) {\r\n throw new RuntimeException(\"Unable to retrieve flight id \" + flightId);\r\n }\r\n Map<String, Object> flight = res.get().contentAsObject().toMap();\r\n results.add(flight);\r\n }\r\n return results;\r\n }\r\n<\/pre>\n public Result<Map<String, Object>> registerFlightForUser(final Bucket bucket,\r\n \tfinal String username, final JsonArray newFlights) {\r\n<\/pre>\n JsonDocument userData = bucket.get(\"user::\" + username);\r\n if (userData == null) {\r\n throw new IllegalStateException();\r\n }\r\n\r\n if (newFlights == null) {\r\n throw new IllegalArgumentException(\"No flights in payload\");\r\n }\r\n\r\n JsonArray added = JsonArray.empty();\r\n<\/pre>\n JsonArray allBookedFlights = userData.content().getArray(\"flights\");\r\n if(allBookedFlights == null) {\r\n allBookedFlights = JsonArray.create();\r\n }\r\n\r\n for (Object newFlight : newFlights) {\r\n checkFlight(newFlight);\r\n JsonObject t = ((JsonObject) newFlight);\r\n t.put(\"bookedon\", \"try-cb-java\");\r\n<\/pre>\n allBookedFlights.add(t);\r\n added.add(t);\r\n }\r\n\r\n userData.content().put(\"flights\", allBookedFlights);\r\n<\/pre>\n
JsonDocument response = bucket.upsert(userData);\r\n\r\n JsonObject responseData = JsonObject.create()\r\n .put(\"added\", added);\r\n\r\n return Result.of(responseData.toMap(), \"Booked flight in Couchbase document \" + response.id());\r\n }\r\n<\/pre>\n
Resources<\/h3>\n