Start with the Python SDK

The Python SDK allows you to write Python code that interfaces with one of the Golem DB chain. You can use it to store entities, update them, and delete them.

In the following instructions, we will:

1. Set up your environment using the Bun runtime.
2. Create Python code that performs typical CRUD operations on Golem DB.
3. Add funds from a "faucet" for our test network, Kaolin.
4. Optionally run the code (unless you already have a private key with funds).

This will provide an easy starting point that you can build on for your own applications.

Configure the Python environment

You can use your preferred Python environment—whether it's virtualenv, conda, or poetry.
All you need to do is install the golem-base-sdk package:

mkdir golem-sdk-practice
cd golem-sdk-practice
pip install golem-base-sdk

Next, create a file (e.g., crud.py). Open your favorite editor and define some initial variables that we’ll use in the next steps:

import asyncio
import uuid

from golem_base_sdk import GolemBaseClient, GolemBaseCreate, Annotation, GolemBaseUpdate, GolemBaseDelete, GenericBytes

GOLEM_DB_RPC = "https://kaolin.holesky.golemdb.io/rpc"
GOLEM_DB_WSS = "wss://kaolin.holesky.golemdb.io/rpc/ws"
PRIVATE_KEY = "<YOUR_PRIVATE_KEY>"

CRUD operations on Golem DB

To perform any operation on Golem DB, we need to create a connected client first:

# Create a client to interact with the GolemDB API
golem_base_client = await GolemBaseClient.create(
    rpc_url=GOLEM_DB_RPC,
    ws_url=GOLEM_DB_WSS,
    private_key=PRIVATE_KEY,
)

Adding a new entity

Once the client is ready, we can create an example entity and store it in Golem DB chain:

# create a new entity with annotations
id = str(uuid.uuid4())
receipt = await golem_base_client.create_entities([GolemBaseCreate(
    b'Test entity',
    600,
    [
        Annotation("testTextAnnotation", "demo"), 
        Annotation("id", id),
    ],
    [
        Annotation("version", 1)
    ]
)])
print(f"Receipt: {receipt}")

golem_base_client.create_entities: This function sends a transaction to the chain containing a properly constructed data field and metadata that allows Golem DB to interpret it correctly.

It takes a list of GolemBaseCreate objects, each with 4 fields (you can include multiple entities in one transaction if desired):

• data: Payload in bytes
• btl: Block-To-Live, the number of blocks the entity will exist (each block is created every ~2 seconds, so BTL can be translated into an expiration time)
• string_annotations: List of text annotations used for querying data
• numeric_annotations: List of numeric annotations used for querying data

If successful, you should receive a receipt of the transaction containing this storage operation.

Query the entity by annotations

As entities are unstructured payloads, annotations are used to query them. To query the previously created entity:

# Query the entity by annotations
entities = await golem_base_client.query_entities(f'id = "{id}" && version = 1')
for entity in entities:
    print(f"Entity: {entity}")

golem_base_client.query_entities: This function takes a query string where annotations can be used with the equality (=) predicate. The < and > operators are also supported, and multiple predicates can be combined using && and ||.

Updating the entity

Updating an entity is very similar to creating one, with one extra parameter — the entity_key of the entity to update.

# Update the entity
receipt = await golem_base_client.update_entities([GolemBaseUpdate(
    receipt[0].entity_key,
    b'Updated entity',
    1200,
    [
        Annotation("id", id)
    ],
    [
        Annotation("version", 2)
    ]
)])
print(f"Receipt: {receipt}")

Updating an entity overrides all of its elements, including the payload, annotations, and BTL.

Deleting the entity

To delete an entity, call golem_base_client.delete_entities and provide the hex-encoded hash (entity key) of the entity you want to remove:

# remove the entity
receipt = await golem_base_client.delete_entities([GolemBaseDelete(
    GenericBytes.from_hex_string(entity_key),
)])
print(f"Receipt: {receipt}")

Adding Funds

To run the examples above, you need to provide a private key with some funds (to pay the transaction fees for mutation operations).

There are many ways to create a private key—for example, you can use MetaMask. Once you have the private key for your account, you must top up its balance on the selected DBChain—in our case, Kaolin.

The easiest way to get test funds is to use the Kaolin faucet:

https://kaolin.holesky.golemdb.io/faucet/

Paste your account address and click Request Funds. After a short while, your account will receive some ETH on the testnet.

Run the code

Once you have completed the crud.py file with the examples above and funded your private key, you can run it with:

python crud.py

---

The complete example (which also includes watching chain event logs) can be found here:

👉 https://github.com/Golem-Base/golemdb-sdk-demos/tree/main/python