Couchbase Server Quickstart with Couchbase Python SDK
Using the Couchbase Python SDK, create new database records in Couchbase and look them up.
This exercise assumes that you are familiar with relational and document databases, and provides a fast-track from zero to secondary lookup using Couchbase Server and Python SDK.
Prerequisite: Run Couchbase Server
-
Couchbase Server 6.5 is already running.
-
An empty bucket named "default" has been created.
-
Both a primary index and an adaptive index have been created and built on the default bucket.
If you still need to perform these tasks please use the following:
The Couchbase Python SDK 3.0 requires Python 3, with Python 3.5 and above supported
Step 1: Install Couchbase Python SDK
# Only needed during first-time setup: sudo apt-get install git-all python3-dev python3-pip python3-setuptools cmake build-essential sudo pip3 install couchbase
# Only needed during first-time setup: sudo yum install gcc gcc-c++ python-devel python-pip cmake sudo pip3 install couchbase
brew update # get list of latest packages brew install python pip3 install couchbase
For more details on installing Couchbase Python SDK 3.0, see the Couchbase Python SDK documentation.
Step 2: Connecting to Couchbase using Python SDK
Let’s first show how to connect with Couchbase so you can access the 'default' bucket using the Python SDK.
# these modules are used to access and authenticate with your database cluster:
from couchbase.cluster import Cluster, ClusterOptions, QueryOptions
from couchbase_core.cluster import PasswordAuthenticator
# specify the cluster and specify an authenticator containing a username and password to be passed to the cluster.
cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('Administrator', 'password')))
# following a successful authentication, a bucket can be opened.
# access a bucket in that cluster
bucket = cluster.bucket('default')
coll = bucket.default_collection()
Step 3: Create and Query a New Document
Suppose we need to store the following data in the database representing 3 distinct users:
user0001 = {
"firstName" : "Perry",
"lastName" : "Mason",
"email" : "perry.mason@acme.com",
"tagLine" : "Who can we get on the case?",
"type" : "user"
}
user0002 = {
"firstName" : "Major",
"lastName" : "Tom",
"email" : "major.tom@acme.com(opens in new tab)",
"tagLine" : "Send me up a drink",
"type" : "user"
}
user0003 = {
"firstName" : "Jerry",
"lastName" : "Wasaracecardriver",
"email" : "jerry.wasaracecardriver@acme.com(opens in new tab)",
"tagLine" : "el sob number one",
"type" : "user"
}
Documents are created using the bucket.insert()
and bucket.insert_multi()
methods. They can also be created using the bucket.upsert()
and bucket.upsert_multi()
methods.
The code to store a single user in the default
bucket would look like the following:
#insert a single document
rv = bucket.upsert('newDoc1', user0001)
print (rv)
-
The
user0001
is defined as a series of JSON key-value pairs. -
The
newDoc1
is the name of the document you want to create.
The code to store multiple users in the default
bucket would look like the following:
rv = bucket.upsert_multi({'newDoc2':user0002, 'newDoc3':user0003})
print (rv)
Since SDK 3.0 all Key-Value operations are executed on the collection level instead of the bucket level. |
To recover the document by the id, you can use the bucket.get()
method.
# first lookup using the key
rv = bucket.get('newDoc2')
print(rv.value)
Finally, here is how you query the database when you need all users where the email ends with @acme.com:
#first secondary lookup to find all users with email ending in @acme.com
query_result = cluster.query('SELECT * FROM `default` WHERE email LIKE $email', QueryOptions(named_parameters={'email': "%@acme.com"}))
for row in query_result:
print(row)
Here is all of the code for our class:
# these modules are used to access and authenticate with your database cluster:
from couchbase.cluster import Cluster, ClusterOptions, QueryOptions
from couchbase_core.cluster import PasswordAuthenticator
# specify the cluster and specify an authenticator containing a username and password to be passed to the cluster.
cluster = Cluster('couchbase://localhost', ClusterOptions(PasswordAuthenticator('Administrator', 'password')))
# following a successful authentication, a bucket can be opened.
# access a bucket in that cluster
bucket = cluster.bucket('default')
coll = bucket.default_collection()
# following a successful authentication, a bucket can be accessed to perform operations
# JSON Object for user0001
user0001 = {
"firstName" : "Perry",
"lastName" : "Mason",
"email" : "perry.mason@acme.com",
"tagLine" : "Who can we get on the case?",
"type" : "user"
}
#insert a single document
rv = bucket.upsert('newDoc1', user0001)
print (rv)
#insert multiple documents
user0002 = {
"firstName" : "Major",
"lastName" : "Tom",
"email" : "major.tom@acme.com(opens in new tab)",
"tagLine" : "Send me up a drink",
"type" : "user"
}
user0003 = {
"firstName" : "Jerry",
"lastName" : "Wasaracecardriver",
"email" : "jerry.wasaracecardriver@acme.com(opens in new tab)",
"tagLine" : "el sob number one",
"type" : "user"
}
rv = bucket.upsert_multi({'newDoc2':user0002, 'newDoc3':user0003})
print (rv)
# first lookup using the key
rv = bucket.get('newDoc2')
print(rv.value)
#first secondary lookup to find all users with email ending in @acme.com
query_result = cluster.query('SELECT * FROM `default` WHERE email LIKE $email', QueryOptions(named_parameters={'email': "%@acme.com"}))
for row in query_result:
print(row)
Make sure you have at least a primary index in your bucket before running the code. |
If you want to run the code to see its output, copy the complete code into a file, say connect.py
, and run python3 connect.py
.