Transition from v3 to v4


The main differences between v3 and v4:

Query language. Documents in v3 are accessed by usingit's native query language. In contrast, v4 uses JS/SQL (JavaScript/SQL) statements, allowing powerfull data transformations in the database.

Storage hierarchy. v4 represents new storage hierarchy: database -> collection -> document. v3 has only two levels: databas -> document.

Stored data format. In v3 data is stored in XML format, but in v4 – in JSON.

This article describes an important things that can help you to migrate from v3 to v4.

Data set migration

There is a difference between stored data format in v3 and v4 database versions. In v3 data is stored in XML format, but in v4 – in JSON. You can import in v4 following data formats – json, xml, csv. It means, that data will be converted to JSON type when you import it in v4 collection.
For example, if your XML document stucture (with attributes) is:

<document>
<name>Schwinn Bike</name>
<category color="white">Bicycles</category>
<_id>BQAAGOOcLw0=</_id>
</document>

When you insert document in v4 collection, it is converted to JSON and will look like:

{
"name": "Schwinn Bike",
"category": "Bicycles",
"category@attribute": {
"color": "white"
},
"_id": "BQAAGOOcLw0="
}

First, you need to export your data set from v3 database by creating export script by your own, or by using "Download as" feature in Cloud UI. Please use .json, .csv or .xml data format to save your documents. Then, you are ready to import prepared data into v4 collection.

Data Indices

In v4 database each collection has Data Model with automatically detected field indexies similary as in v3. You can change Data Model and override field indexies, if it is needed. More about v4 Data Model and indexies you can learn here.

Analogical commands

v3 uses it's native query language, but v4 comes with new JS/SQL query language. Here are simple examples how to convert requests:

Command
v3
v4
INSERT
...
<cps:command>insert</cps:command>
<cps:content>
<document>
<name>Schwinn Bike</name>
<category >Bicycles</category>
</document>
</cps:content>
...
INSERT INTO collection JSON VALUE {
  "name": "Schwinn Bike",
  "category": "Bicycles"
}

More about INSERT

UPDATE
...
<cps:command>update</cps:command>
<cps:content>
<document>
<name>Schwinn Bicycle</name>
<category >Bike</category>
<_id>BQAAGOOcLw0=</id>
</document>
</cps:content>
...
UPDATE collection["BQAAGOOcLw0="] SET {
  "name": "Schwinn Bicycle",
  "category": "Bike"
}

More about UPDATE

SEARCH/SELECT
...
<cps:command>search</cps:command>
<cps:content>
<query>*</query>
</cps:content>
...
SELECT *
FROM collection

More about SELECT

DELETE
...
<cps:command>delete</cps:command>
<cps:content>
<document>
<_id>BQAAGOOcLw0=</_id>
</document>
</cps:content>
...
DELETE collection["BQAA GOOcLw0"]

More about DELETE

REPLACE
...
<cps:command>delete</cps:command>
<cps:content>
<document>
<_id>BQAAGOOcLw0=</_id>

<name>Schwinn Super Bicycle</name>
</document>
</cps:content>
...
REPLACE collection["BQAAGOOLw0="] WITH JSON VALUE {
"name":"Schsinn Super Bicycle"
}

More about REPLACE

Query syntax transformation

Statement
v3
v4

Equality and comparisons: compare field to a string value

<query>
<name>Super Bicycle</name>
</query>
SELECT * FROM collection WHERE name == "Super Bicycle"
More about equality and comparison

Equality and comparisons: compare field to a numeric value

<query>
<price>&gt; 300.00</price>
</query>
SELECT * FROM collection WHERE price > 300.00
More about equality and comparison

Boolean expressions: AND/OR/NOT

<query>
<name>Super Bicycle</name>{<category>~Bike</category><price>&gt;300.00</price>}
</query>
SELECT * FROM collection WHERE name == "Super Bicycle" && (category !="Bike" || price > 300.00)
More about boolean expressions

Full text search

<query>Mountain Bike</query>
SELECT * FROM collection WHERE CONTAINS("Mountain Bike")
More about FTS

SNIPPET/HIGHLIGH

<query><name>Super Bicycle</name></query>
<list>
<name>highlight</name>
<category>snippet</category>
</list>
SELECT *, name.HIGHLIGHT(), category.SNIPPET()
FROM collection WHERE name == "Super Bicycle"
More about Snippet and Highlihting

Numeric ordering

<query>Mountain Bike</query>
<ordering>
<numeric>
<price>descending</price>
</numeric>
</ordering>
SELECT * FROM collection WHERE CONTAINS("Mountain Bike")
ORDER BY price DESC
More about ORDER BY

Alphabetic ordering

<query><price>&lt; 300</price>
</query>
<ordering>
<string>
<category>ascending,en</category>
</string>
</ordering>
SELECT * FROM collection WHERE price < 300
ORDER BY category ASC
More about ORDER BY

Grouping

<query><price>&lt; 300</price>
</query>
<aggregate>category GROUP BY category</aggregate>

SELECT * FROM collection WHERE price < 300
GROUP BY category
More about GROUP BY