CFCouchbase SDK
Search…
What's New With 2.0.0
More than two years have passed since our SDK v1.1 was released. The SDK has been updated to support the new functionality available in Couchbase Server 4.x, including:
- N1QL Queries
- GSI Indexes
- Replica Reads
- Document Locking
- Prepared Statements
- Improved Design Document Management
- Expanded Configuration Options
- And more...
Changes
CFCouchbase uses the Java SDK from Couchbase, when it went from version 1.x to 2.x breaking changes occurred (for the better). We have tried to mitigate these changes where possible. Many methods that were removed from the Java SDK and we created as facades for backwards compatibility. All of these methods have been marked from deprecation, but are still supported for the time being.
add()=>insert()decr()=>counter()incr()=>counter()delete()=>remove()set()=>upsert()setMulti()=>upsertMulti()setWithCAS()>replaceWithCAS()
The SDK also brings many new methods, some of which we will cover in detail.
exists()getAndLock()getEnvironment()getFromReplica()invalidateQueryCache()n1qlQuery()publishDesignDocument()replace()unlock()
N1QL Queries
One of the biggest additions to the SDK is support for N1QL (pronounced "nickel"). N1QL is a "SQL like" syntax for working with JSON documents in Couchbase Server. You can perform a N1QL query by calling the
query(type="n1ql", statement="...") method or by calling the n1qlQuery("...") method directly. Just as with View queries, the same options are available to N1QL queries, this includes:deserializedeserializeOptionsinflateTofiltertransform
The most basic (and fastest) N1QL operation is to retrieve document(s) by their document id.
1
// query
2
couchbase.n1qlQuery('
3
SELECT u.*
4
FROM users AS u
5
USE KEYS "user_101"
6
');
Copied!
Notice the
FROM clause, in this example "users" is the name of a bucket. This query can be described as:"Get every property from the 'user_101' document in the 'users' bucket"
All N1QL queries will return an array, the response from this query would return an array of structures.
1
[
2
{
3
"email": "[email protected]",
4
"first_name": "Albin",
5
"last_name": "Price",
6
"user_id": 101,
7
"username": "Eudora43"
8
}
9
]
Copied!
The
USE KEYS statement is not limited to single values either, multiple documents can be retrieved by declaring an array.1
couchbase.n1qlQuery('
2
SELECT u.*
3
FROM users AS u
4
USE KEYS [ "user_101", "user_454" ]
5
');
Copied!
N1QL supports the standard DML operations that you would expect.
1
// insert a new document
2
couchbase.n1qlQuery('
3
INSERT INTO users (KEY, VALUE)
4
VALUES ("user_2343", {
5
"user_id": 2343,
6
"name": "John Smith",
7
"email": "[email protected]"
8
})
9
');
10
​
11
// update a specific property of a document
12
couchbase.n1qlQuery('
13
UPDATE users
14
USE KEYS "user_2343"
15
SET email = "[email protected]"
16
');
17
​
18
// remove a document
19
couchbase.n1qlQuery('
20
DELETE
21
FROM users
22
USE KEYS "user_2343"
23
');
24
​
25
// update or insert an entire document
26
couchbase.n1qlQuery('
27
UPSERT INTO users (KEY, VALUE)
28
VALUES ("user_2343", {
29
"user_id": 2343,
30
"name": "John Smith",
31
"email": "[email protected]"
32
})
33
');
Copied!
Up to this point our queries have used just an ID when working with documents. What if we wanted to find documents based on a properties value? To do this we need to create GSI (Global Secondary) Indexes.
1
// create an index of usernames
2
couchbase.n1qlQuery('
3
CREATE INDEX idx_users_username
4
ON ecommerce( username )
5
USING GSI
6
');
7
​
8
// query based on username
9
couchbase.n1qlQuery('
10
SELECT users.*
11
FROM ecommerce AS users
12
WHERE users.username = 'Eudora43'
13
');
Copied!
There are several options for creating indexes, such as partitioning, building, covering, array indexing, etc. that are not covered in this post.
A common practice in SQL is to
JOIN results across tables. N1QL supports joining results in a bucket as well as across buckets. JOIN statements utilize the USE KEYS clause.1
// query to get all of the orders by username
2
couchbase.n1qlQuery('
3
SELECT orders.order_id, orders.order_date, orders.total
4
FROM ecommerce AS users
5
INNER JOIN ecommerce AS orders
6
ON KEYS users.order_history
7
WHERE u.username = 'Eudora43'
8
');
Copied!
Document Locking
There may be instances where your application needs to prevent retrieval and updates to a given document. Document updates can be prevented by using the CAS operations, but this is not always guaranteed. The 2.0 SDK allows you to retrieve a document and lock it (for up to 30 seconds), then unlock it by updating it with CAS value at a later point in time.
1
// get the user document and lock it
2
user = couchbase.getAndLock("user_101");
3
​
4
// update and unlock the document using CAS
5
couchbase.replaceWithCAS(
6
id="user_101",
7
value=doc,
8
cas=user.cas
9
);
10
​
11
// unlock the document without updating it
12
couchbase.unlock(
13
id="user_101",
14
cas=user.cas
15
);
Copied!
Calls to retrieve or update document that has been locked, will fail until the document has been successfully unlocked or the maximum time of 30 seconds has passed.
Config
There are 44 new configuration options supported by the SDK. The options will allow you to tweak and tune your configuration to meet your needs. Examples include
caseSensitiveKeys, connectTimeout, sslEnabled, queryTimeout. Please see the documentation for detailed descriptions of each configuration option.With the changes from the 1.x to 2.x SDK the following configuration options are no longer supported:
- maxReconnectDelay
- obsPollInterval
- obsPollMax
- opQueueMaxBlockTime
- opTimeout
- readBufferSize
- shouldOptimize
- timeoutExceptionThreshold
Resources
Last modified 4yr ago
Copy link
Edit on GitHub