Package: kwil
kwil.pyBorrows heavily fromweb3.pykwil.pyWhat is Kwil?InstallationConfigurationProvidersPrivate KeyAPIhelpershigh level APIlow level API (Kwil.kwild API)Fetching dataMaking transactionsUsageConnect to Kwil nodeDeploy DatabaseWorking with ActionsLicenseWhat is Kwil?Kwil is a blockchain-based database platform, while keep being blockchain agnostic on Account.
To use Kwil.py, you need to do the following:Create a Ethereum accountFund the account with some required TOKEN of your kwil providerCreate database schema, through Kwil Kuneiform IDE. From there, you can get compiled schema bytes.Deploy the database schema to the blockchain.Create/Update data through predefined Actions.InstallationpipinstallkwilSupported python version:3.93.10ConfigurationProvidersProviders are used to interact with the blockchain. They are responsible for sending and receiving RPC requests.
There are following builtin providers:GRPCProvider - connects to a remote gRPC based serverPrivate KeyKwil now support Ethereum private key to sign transaction. This key is also associated
with an Ethereum account which needed to be funded to use Kwil.APIThere areexamplesthat shows how to use these API.helpersKwil.generate_dbi(owner_addr, dataset_name)Kwil.load_wallet(private_key)high level APIkwil.deploy_database(payload)- deploys a new database, payload is compiled bytes of schemakwil.get_schema(db_identifier)- returns the database schemakwil.list_databases(OPTIONAL[owner_address])- returns the list of databases under current accountkwil.drop_database(dataset_name)- drops the database under current accountkwil.execute_action(db_identifier, action_name, inputs)- executes the action on the databasekwil.query(db_identifier, query)- executes query(ad-hoc SQL) on the databaselow level API (Kwil.kwild API)Fetching dataKwil.kwild.ping()Kwil.kwild.get_config()- returns the configuration of the nodeKwil.kwild.get_schema(DBIdentifier)- returns the dataset schema infoKwil.kwild.get_account(Adddress)- returns the account info(nonce, balance, etc)Kwil.kwild.estimate_price(TxParams)- returns the estimated price for the transactionKwil.kwild.query(DBIdentifier, Query)- returns the query(ad-hoc SQL) resultKwil.kwild.list_databases()- returns the list of databases under current accountMaking transactionsKwil.kwild.broadcast(TxParams)- broadcasts the transaction to the networkUsageThere are more examples inexamplesfolder.Connect to Kwil nodeKwil.py will connect to a Kwil node through a provider.
Currently, only GRPC provider is supported.>>> from kwil import Kwil
>>> kwil = Kwil(Kwil.GRPCProvider("localhost:50051"),
                Kwil.load_wallet("YOUR_ETH_PRIVATE_KEY"))
>>> kwil.is_connected()
TrueDeploy DatabaseAssume we have our schema defined and compiled(./test_db.json). We can deploy the schema to the blockchain.First, create a provider usingKwil.GRPCProvider.Then, create aKwilinstance, can calldeploy_databaseto deploy the schema to the blockchain.Finally, calllist_databaseto list all the databases under current account to verify it's there.importloggingfromkwilimportKwil# assume that account has enough fund# here we use examples/test_db.kf as our dataset schema, we'll use examples/test_db.json(compiled schema)# create clientclient=Kwil(Kwil.GRPCProvider("localhost:50051"),Kwil.load_wallet("YOUR_ETH_PRIVATE_KEY"))# create datasetwithopen("./test_db.json","r")asf:schema_json=f.read()try:client.deploy_database(schema_json.encode("utf-8"))exceptExceptionase:logging.exception(e)# list datasetdbs=client.list_databases()print("datasets after create: ",dbs)Working with Actions# execute an actiondb_name="testdb"# The name of the database, from the schema filedb_id=Kwil.generate_dbi(client.wallet.address,db_name)action="create_user"tx_receipt=client.execute_action(db_id,action,# `create_user` is defined in examples/test_db.kf[{"$id":1,"$username":"aha","$age":18}])result=tx_receipt["result"]print("create user result: ",result)# execute a pre-defined query through actionaction="list_users"tx_receipt=client.execute_action(db_id,action,[])result=tx_receipt["result"]print("list user result:",result)Let's extend the example above. We can callexecute_actionto execute an action on the database.
In our schema(examples/test_db.kf), we haveaction create_user($id, $username, $age) public {
    INSERT INTO users (id, username, age, wallet)
    VALUES ($id, $username, $age, @caller);
}create_useris a public action, so we can call it without any permission.To call this action, we need to provide the dataset identifier, action name and inputs.tx_receipt=client.execute_action(db_id,action,[{"$id":1,"$username":"aha","$age":18}])Here, we only create one user, the inputs is just a dict of the input parameters with values.LicenseMIT