Data Definition API


Clusterpoint supports database/collection creation and modification not only through Cloud Web UI, but also through API by using DDL. DDL syntax allows to execute collection creation, editing and configuration requests through API. For each DDL command POST method should be used.

For DDL API commands, please refer to the links: PHP, Node.js.

Create Collection

The CREATE COLLECTION command is used to establish new collection in existing database or new collection and new database.

Syntax:

CREATE COLLECTION database_name.collection_name

This command creates new collection (or new database and new collection, if defined database does not exist) with the default values - 1 shard and 1 replica, default Data Model for "_id" field. But you can manage your collection parameters at creation time by using additional options.

Additional CREATE COLLECTION arguments:

CREATE COLLECTION <database_name.collection_name>
[WITH <shard_count> SHARDS]
[WITH <replica_count> REPLICAS]
[WITH HYPERREPLICATION]
[WITH DATA MODEL <data_model>]
[WITH CONFIG <config>]

Please, find detailed description for each option below.

With Specific Layout

By default command CREATE COLLECTION creates collection with 1 shard and 1 replica. But you can configure count of shards and replicas by using following syntax (in this example we create collection with 3 shards and 3 replicas):

CREATE COLLECTION database_name.collection_name
WITH 3 SHARDS
WITH 3 REPLICAS

With Hyperreplication

If you are goint to use JOINs to operate objects from different collections in the same query, one of collections should be hyper-relicated. It is possible to create hyper-replicated collection through DDL:

CREATE COLLECTION database_name.collection_name
WITH HYPERREPLICATION

With Specific Data Model

You can predefine Data Model indexes for document fields before data is inserted into collection by using following syntax:

CREATE COLLECTION database_name.collection_name
WITH DATA MODEL
<data_model>

Here is an example of specific Data Model definition (indexes for three fields are being set):

CREATE COLLECTION database_name.collection_name
WITH DATA MODEL [ { "path": "custom_id", "type": [ "id" ] }, { "path": "field_1", "rank_from": 1, "rank_to": 10,
"stem_lang": [
"fr", "nl"
], "type": [ "text", "string" ] }, { "path": "nested.int_field", "type": [ "integer" ] } ]

Note: when you create collection, ID field is assigned automatically - "_id". But you can change the name of ID field when you create collection (in this example - "custom_id"). After collection is created - name of the ID field "_id" could not be changed.

Setting Data Model Rules

Clusterpoint discovers field names and their types automatically and records index values into Data Model when documents are inserted into collection. Data Model could be changed and overriden. Overriden Data Model values are more significant as automatically detected.
Detailed information about Data Model rules is available in the article Collection Data Model.

When you create/edit collection and specify index rules, you can use the following values:

- "type" - float, integer, string, boolean, text.
"Text" type enables Full Text Search for the certain field and content of the field will be searchable with CONTAINS operator.

- "rank_from" & "rank_to" - the weight interval for the fields that are indexed as "text" specifies the range of weights that are used for relevance ranking.

- "stem_lang" - with stemming rule it is possible to include a word and its declinations in SELECT queries; possible values for the stem-lang parameter are listed in Web UI Data Model.

Edit Collection

With EDIT COLLECTION you can change existing Data Model (override it) and set Configuration rules.

General syntax:

EDIT COLLECTION database_name.collection_name
[SET DATA MODEL <data_model>]
[SET CONFIG <config>]

Edit collection with specified Data Model replaces Data Model fully, excepting ID field - modification of ID field is forbidden. You should include existing ID field in the Data Model definition, please refer to the example below. This example would change all indexes to the new one and leave only _id field in Data Model. And would add collection configuration - description and special symbols:

EDIT COLLECTION database_name.collection_name
SET DATA MODEL [
{
"path": "_id",
"type": [
"id"
]
},
{
"path": "address",
"type": [
"string"
]
},
{
"path": "postcode",
"type": [
"float","string"
]
}, { "path": "body", "rank_from": 1, "rank_to": 10, "type": [ "text", "string" ] }, { "path": "do_not_index", "type": [] }
]
SET CONFIG
[
{ "description": "My test collection",
"index":{ "specsymbols":"<?%"}
}
]

You can use SET DATA MODEL and SET CONFIG together in one request or separately.

Note: do not forget to Reindex collection after changes in Data Model or Configuration are made, in order to assign new indexes for existing documents.

Reindex Collection

When you change Data Model indexes or Configuration rules, it is necessary to Reindex collection in order to activate new configuration for existing and new documents.

REINDEX COLLECTION database_name.collection_name
[IN BACKGROUND]

By using additional parameter you can execute reindex "in background". Reindex "in background" means, that while it is running, old configurtion is valid and all select requests are performed according to old indexes. And as Reindex is completed, the new becomes active.

Clear Collection

The CLEAR COLLECTION removes all documents and auto-detected data types in Data Model from the collection.

CLEAR COLLECTION database_name.collection_name

Drop Collection

The DROP COLLECTION deletes collection from the database. If you drop the last collection in the database, then command deletes database too.

DROP COLLECTION database_name.collection_name

Drop Database

With the DROP DATABASE you can delete database and all collections that database contains.

DROP DATABASE database_name

Describe Collection

The DESCRIBE COLLECTION command returns technical information about collection - shard and replica count, Data Model overrides, etc.

DESCRIBE COLLECTION database_name.collection_name

List Databases

The LIST DATABASES returns the list with all v4 databases, but do not show the content of databases - collections.

LIST DATABASES

List Collections

The LIST COLLECTIONS returns the list with all v4 collections.

The LIST COLLECTIONS FROM allows to get the list with all collections that are created under the certain database:

LIST COLLECTIONS [FROM database_name]