Skip to main content

Quickstart

note

If you are new to Macrometa GDN, we strongly recommend reading Essentials of Macrometa GDN.

Documents in GDN are JSON objects. These objects can be nested (to any depth) and may contain lists. Each document has a unique primary key which identifies it within its collection. Furthermore, each document is uniquely identified by its document handle across all collections. Different revisions of the same document (identified by its handle) can be distinguished by their document revision. Any transaction only ever sees a single revision of a document.

For example:

{
"_id" : "myusers/3456789",
"_key" : "3456789",
"_rev" : "14253647",
"firstName" : "John",
"lastName" : "Doe",
"address" : {
"street" : "Road To Nowhere 1",
"city" : "Gotham"
},
"hobbies" : [
{name: "swimming", howFavorite: 10},
{name: "biking", howFavorite: 6},
{name: "programming", howFavorite: 4}
]
}

All documents contain special attributes:

The value of the _key attribute can be specified by the user when creating a document. _id and _key values are immutable once the document has been created. The _rev value is maintained by GDN automatically.

Pre-requisite

Let's assume your

Driver download


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

The first step in using GDN is to establish a connection to a region. When this code executes, it initializes the server connection to the *closest region to your location.

  from c8 import C8Client

print("--- Connecting to C8")
# Simple Way
client = C8Client(protocol='https', host='gdn.paas.macrometa.io', port=443,
email='[email protected]', password='xxxxx',
geofabric='_system')

# To use advanced options
client = C8Client(protocol='https', host='gdn.paas.macrometa.io', port=443)

Get GeoFabric Details

To get details of fabric,

  from c8 import C8Client
client = C8Client(protocol='https', host='gdn.paas.macrometa.io', port=443,
email='[email protected]', password='xxxxx',
geofabric='_system')
print("Get geo fabric details...")
print(client.get_fabric_details())

Create Collection

We can now create collection in the fabric. To do this, first you connect to fabric and then create a collection called employees.

The below example shows the steps.

  # Simple Approach
client = C8Client(protocol='https', host='gdn.paas.macrometa.io', port=443,
email='[email protected]', password='xxxxx',
geofabric='_system')
client.create_collection(name='employees')

Create Index

Let's add a hash_index called emails to our collection employees. Please refer to reference guide for details on other available index types.

  # Simple Approach
client = C8Client(protocol='https', host='gdn.paas.macrometa.io', port=443,
email='[email protected]', password='xxxxx',
geofabric='_system')
print("Add Hash Index", client.add_hash_index('employees', fields=['continent', 'country'], unique=True)
)

Insert Documents

Let's insert documents to the employees collection as shown below.

  # Simple Approach
client = C8Client(protocol='https', host='gdn.paas.macrometa.io', port=443,
email='[email protected]', password='xxxxx',
geofabric='_system')
client.insert_document(collection_name='employees', document={'_key':'Jean', 'firstname': 'Jean', 'lastname':'Picard', 'email':'[email protected]'})

docs = [
{'_kefabricy':'James', 'firstname': 'James', 'lastname':'Kirk', 'email':'[email protected]'},
{'_kefabricy': 'Han', 'firstname': 'Han', 'lastname':'Solo', 'email':'[email protected]'},
{'_kefabricy': 'Bruce', 'firstname': 'Bruce', 'lastname':'Wayne', 'email':'[email protected]'}
]

client.insert_document(collection_name='employees', document=docs)

Query documents using C8QL

C8QL is C8's query language. You can execute C8QL query on our newly created collection employees to get its contents.

The query FOR employee IN employees RETURN employee is equivalent to SQL's SELECT query.

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

client.execute_query('FOR employee IN employees RETURN employee')

Get realtime updates

Example for real-time updates from a collection in fabric:

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

#--------------------------------------------------------------
def callback_fn(event):
print(event)
#--------------------------------------------------------------
client.on_change("employees", callback=callback_fn)

Query as API

Query as API (aka RESTQL) enables developers to quickly convert saved C8QL queries into geo-distributed REST APIs. This eliminates the need for separate backend servers & containers for CRUD operations.

  from c8 import C8Client

fed_url = "gdn.paas.macrometa.io"
guest_mail = "[email protected]"
guest_password = "xxxxxx"
geo_fabric = "_system"
collection_name = "person"

value = "INSERT {'firstname':@firstname, 'lastname':@lastname, 'email':@email, 'zipcode':@zipcode, '_key': 'abc'} IN %s" % collection_name
parameter = {"firstname": "", "lastname": "", "email": "", "zipcode": ""}

insert_data = {"query": {"name": "insertRecord", "parameter": parameter, "value": value}}
get_data = {"query": {"name": "getRecords", "value": "FOR doc IN %s RETURN doc" % collection_name}}
update_data = {"query": {"name": "updateRecord", "value": "UPDATE 'abc' WITH { \"lastname\": \"cena\" } IN %s" % collection_name }}
delete_data= {"query": {"name": "deleteRecord", "value": "REMOVE 'abc' IN %s" % collection_name}}
get_count = {"query": {"name": "countRecords", "value": "RETURN COUNT(FOR doc IN %s RETURN 1)" % collection_name}}

if __name__ == '__main__':

print("\n ------- CONNECTION SETUP ------")
print("tenant: {}, geofabric:{}".format(guest_mail, geo_fabric))
client = C8Client(protocol='https', host=fed_url, port=443,
email=guest_mail, password=guest_password,
geofabric=geo_fabric)

print("\n ------- CREATE GEO-REPLICATED COLLECTION ------")
if client.has_collection(collection_name):
print("Collection exists")
else:
employees = client.create_collection(collection_name)
print("Created collection: {}".format(collection_name))

print("\n ------- CREATE RESTQLs ------")
client.create_restql(insert_data) # name: insertRecord
client.create_restql(get_data) # name: getRecords
client.create_restql(update_data) # name: updateRecord
client.create_restql(delete_data) # name: deleteRecord
client.create_restql(get_count) # name: countRecords
print("Created RESTQLs:{}".format(client.get_restqls()))

print("\n ------- EXECUTE RESTQLs ------")
print("Insert data....")
response = client.execute_restql(
"insertRecord",
{"bindVars": {"firstname": "john", "lastname": "doe",
"email": "[email protected]", "zipcode": "511037"}})
print("Get data....")
response = client.execute_restql("getRecords")
print("Update data....")
response = client.execute_restql("updateRecord")
print("Get data....")
response = client.execute_restql("getRecords")
print("Count records....")
response = client.execute_restql("countRecords")
print("Delete data....")
response = client.execute_restql("deleteRecord")

print("\n ------- DELETE RESTQLs ------")
client.delete_restql("insertRecord")
client.delete_restql("getRecords")
client.delete_restql("updateRecord")
client.delete_restql("countRecords")
client.delete_restql("deleteRecord")

print("\n ------- DONE ------")