Skip to main content

Key-Value Store

A key-value collection stores data in the form of a dictionary. This requires a key for each record and a corresponding value that contains the data. Each document in the database must have a unique key, similar to the concept of a primary key. Key-value databases are known for being quick and storage efficient resulting in faster CRUD (Create, Read, Update, Delete) operations.

In GDN, each document stored in a collection contains a _key, and the rest of the document is its value. The only key-value operations available are key lookups (single and batch) and key-value pair insertions and updates. If no sharding attribute is specified, _key is used for sharding the data instead.

Key-value collections are always global. You can specify time_to_live (TTL) during creation.

For the following examples, assume these credentials:

SDK download

Download the appropriate SDK for Python or JavaScript.

  pyC8 requires Python 3.5+. Python 3.6 or higher is recommended

To install pyC8, simply run

$ pip3 install pyC8

or, if you prefer to use conda:

conda install -c conda-forge pyC8

or pipenv:

pipenv install --pre pyC8

Once the installation process is finished, you can begin developing applications in Python.

Connect to GDN

Establish connection to a local region. When this code runs, it initializes the server connection to the region URL you specify. You can create an API key from the GUI or REST API.

  from c8 import C8Client

# Simple Way
print("--- Connecting to C8")
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
email='nemo@nautilus.com', password="xxxxxx",
geofabric='_system')

# Or Using token
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
token="XXXX")

# Or Using API Key
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey="<your-api-key>")

Create Collection

Create a Collection for saving the key-value pairs.

  from c8 import C8Client

key = "<your-api-key>"
collection_name = "students"

# Create a connection to gdn
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey=key)

# Create a new collection if it does not exist
if client.has_collection(collection_name):
print("Collection exists")
else:
client.create_collection_kv(name=collection_name)

Insert Key Value Pairs

Insert key-value pairs into the collection.

  from c8 import C8Client

key = "<your-api-key>"
collection_name = "students"

# Create a connection to gdn
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey=key)
# Insert Key Value pairs
data = [
{
"_key": "John",
"value": "Science",
"expireAt": 0
},
{
"_key": "Alice",
"value": "Maths",
"expireAt": 0
},
{
"_key": "Alex",
"value": "Physics",
"expireAt": 0
},
{
"_key": "Monika",
"value": "Chemistry",
"expireAt": 0
}
]

client.insert_key_value_pair(collection_name, data)
print("KV Pairs Inserted")

Get Value

Get value for a given key.

  from c8 import C8Client

key = "<your-api-key>"
collection_name = "students"

# Create a connection to gdn
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey=key)
# Get value for a key
print("Value for the provided key: ",client.get_value_for_key(collection_name, "Monika"))

Get Key-Value Count

Get key-value count from a given collection.

  from c8 import C8Client

key = "<your-api-key>"
collection_name = "students"

# Create a connection to gdn
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey=key)

# Get KV count of a collection
print("Number of kv pairs in your collection: ",client.get_kv_count(collection_name))

Update Value

Update value for a given key.

  from c8 import C8Client

key = "<your-api-key>"
collection_name = "students"

# Create a connection to gdn
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey=key)

# Update value for a key
data = {
"_key": "John",
"value": "Biology",
"expireAt": 0
}
client.insert_key_value_pair(collection_name, data)
print("Updated the specified KV pair")

Delete Key-Value

Delete key-value pairs from a collection.

  from c8 import C8Client

key = "<your-api-key>"
collection_name = "students"

# Create a connection to gdn
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey=key)

# Delete entry for a key
print("Deleted Entry for the specified Key: ",client.delete_entry_for_key(collection_name, "John"))

# Delete entry for multiple keys
print("Deleted Entries for the list of keys: ",client.delete_entry_for_keys(collection_name, ["Monika", "Alex", "Alice"]))

Delete Collection

Delete key-value collection

  from c8 import C8Client

key = "<your-api-key>"
collection_name = "students"

# Create a connection to gdn
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey=key)

# Delete Collection
print("Collection Deleted: ",client.delete_collection_kv(collection_name))

Complete Example

The following complete examples are a composite of the previous code snippets:

  from c8 import C8Client

key = "<your-api-key>"
collection_name = "students"

# Create a connection to gdn
client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
apikey=key)

# client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
# email='nemo@nautilus.com', password="xxxxxx",
# geofabric='_system')

# OR Using token
# client = C8Client(protocol='https', host='play.paas.macrometa.io', port=443,
# token="XXXX")


# Create a new collection if it does not exist
if client.has_collection(collection_name):
print("Collection exists")
else:
client.create_collection_kv(name=collection_name)

# Insert Key Value pairs
data = [
{
"_key": "John",
"value": "Science",
"expireAt": 0
},
{
"_key": "Alice",
"value": "Maths",
"expireAt": 0
},
{
"_key": "Alex",
"value": "Physics",
"expireAt": 0
},
{
"_key": "Monika",
"value": "Chemistry",
"expireAt": 0
}
]

client.insert_key_value_pair(collection_name, data)
print("KV Pairs Inserted")

# Get value for a key
print("Value for the provided key: ",client.get_value_for_key(collection_name, "Monika"))

# Get KV count of a collection
print("Number of kv pairs in your collection: ",client.get_kv_count(collection_name))

# Update value for a key
data = {
"_key": "John",
"value": "Biology",
"expireAt": 0
}
client.insert_key_value_pair(collection_name, data)
print("Updated the specified KV pair")

# Delete entry for a key
print("Deleted Entry for the specified Key: ",client.delete_entry_for_key(collection_name, "John"))

# Delete entry for multiple keys
print("Deleted Entries for the list of keys: ",client.delete_entry_for_keys(collection_name, ["Monika", "Alex", "Alice"]))

# Delete Collection
print("Collection Deleted: ",client.delete_collection_kv(collection_name))