Skip to main content

Quickstart

Macrometa GDN is a geodistributed real-time coordination-free materialized views engine that supports multiple data models. You can use GDN as a geo-replicated real-time key-value datastore or database.

If you are new to Macrometa GDN, start by reading the essentials of Macrometa GDN.

Each document stored in a collection (or table) contains a primary key _key. The rest of the document is considered a value. The collection behaves like a simple key-value (KV) store if it has no secondary indexes.

The key-value store has no query languages. The permissible operations are key look-ups (single & batch) and key-value pair insertions, updates and deletions. If you don't specify a sharding attribute, we use _key to shard the data. The simplicity of this model makes a key-value store fast, easy to use, scalable, portable, and flexible.

You can enable time_to_live (TTL) during collection creation and add an expireAt value to specify the expiration time for each document in the KV collection.

For the following examples, assume these credentials:

Driver download

Download the appropriate drivers 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='gdn.paas.macrometa.io', port=443,
email='[email protected]', password="xxxxxx",
geofabric='_system')

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

# Or Using API Key
client = C8Client(protocol='https', host='gdn.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='gdn.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='gdn.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='gdn.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='gdn.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='gdn.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='gdn.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='gdn.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='gdn.paas.macrometa.io', port=443,
apikey=key)

# client = C8Client(protocol='https', host='gdn.paas.macrometa.io', port=443,
# email='[email protected]', password="xxxxxx",
# geofabric='_system')

# OR Using token
# client = C8Client(protocol='https', host='gdn.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))