[docs] Python updates for development page Updates to the Developing Applications with Kudu page for Python. Additionally, this updates some of the github example references.
Change-Id: I028e86b6bc35f36fd1a4752b52463f5d0fd75f76 Reviewed-on: http://gerrit.cloudera.org:8080/4586 Reviewed-by: David Ribeiro Alves <[email protected]> Tested-by: Kudu Jenkins Project: http://git-wip-us.apache.org/repos/asf/kudu/repo Commit: http://git-wip-us.apache.org/repos/asf/kudu/commit/63fdc0c9 Tree: http://git-wip-us.apache.org/repos/asf/kudu/tree/63fdc0c9 Diff: http://git-wip-us.apache.org/repos/asf/kudu/diff/63fdc0c9 Branch: refs/heads/master Commit: 63fdc0c9f49e55ac043c9ba25e9b755b696d405d Parents: 9c8c080 Author: Jordan Birdsell <[email protected]> Authored: Sat Oct 1 15:09:43 2016 -0400 Committer: Jordan Birdsell <[email protected]> Committed: Thu Nov 10 21:34:37 2016 +0000 ---------------------------------------------------------------------- docs/developing.adoc | 79 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 72 insertions(+), 7 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/kudu/blob/63fdc0c9/docs/developing.adoc ---------------------------------------------------------------------- diff --git a/docs/developing.adoc b/docs/developing.adoc index 8833369..03c8cdc 100644 --- a/docs/developing.adoc +++ b/docs/developing.adoc @@ -28,9 +28,8 @@ :sectlinks: :experimental: -Kudu provides C++ and Java client APIs, as well as reference examples to illustrate -their use. A Python API is included, but it is currently considered experimental, -unstable, and subject to change at any time. +Kudu provides C++, Java and Python client APIs, as well as reference examples to illustrate +their use. WARNING: Use of server-side or private interfaces is not supported, and interfaces which are not part of public APIs have no stability guarantees. @@ -48,13 +47,18 @@ set up a virtual machine to run Kudu. The following list includes some of the examples that are available today. Check the repository itself in case this list goes out of date. -`java-example`:: +`java/java-example`:: A simple Java application which connects to a Kudu instance, creates a table, writes data to it, then drops the table. -`collectl`:: +`java/collectl`:: A small Java application which listens on a TCP socket for time series data corresponding to the Collectl wire protocol. The commonly-available collectl tool can be used to send example data to the server. -`clients/python`:: - An experimental Python client for Kudu. +`java/insert-loadgen`:: + A Java application that generates random insert load. +`python/dstat-kudu`:: + An example program that shows how to use the Kudu Python API to load data into a new / existing Kudu table + generated by an external program, `dstat` in this case. +`python/graphite-kudu`:: + An experimental plugin for using graphite-web with Kudu as a backend. `demo-vm-setup`:: Scripts to download and run a VirtualBox virtual machine with Kudu already installed. See link:quickstart.html[Quickstart] for more information. @@ -151,6 +155,67 @@ kuduContext.tableExists("another_table") kuduContext.deleteTable("unwanted_table") ---- +=== Kudu Python Client +The Kudu Python client provides a Python friendly interface to the C++ client API. +The sample below demonstrates the use of part of the Python client. +[source,python] +---- +import kudu +from kudu.client import Partitioning +from datetime import datetime + +# Connect to Kudu master server +client = kudu.connect(host='kudu.master', port=7051) + +# Define a schema for a new table +builder = kudu.schema_builder() +builder.add_column('key').type(kudu.int64).nullable(False).primary_key() +builder.add_column('ts_val', type_=kudu.unixtime_micros, nullable=False, compression='lz4') +schema = builder.build() + +# Define partitioning schema +partitioning = Partitioning().add_hash_partitions(column_names=['key'], num_buckets=3) + +# Create new table +client.create_table('python-example', schema, partitioning) + +# Open a table +table = client.table('python-example') + +# Create a new session so that we can apply write operations +session = client.new_session() + +# Insert a row +op = table.new_insert({'key': 1, 'ts_val': datetime.utcnow()}) +session.apply(op) + +# Upsert a row +op = table.new_upsert({'key': 2, 'ts_val': "2016-01-01T00:00:00.000000"}) +session.apply(op) + +# Updating a row +op = table.new_update({'key': 1, 'ts_val': ("2017-01-01", "%Y-%m-%d")}) +session.apply(op) + +# Delete a row +op = table.new_delete({'key': 2}) +session.apply(op) + +# Flush write operations, if failures occur, capture print them. +try: + session.flush() +except kudu.KuduBadStatus as e: + print(session.get_pending_errors()) + +# Create a scanner and add a predicate +scanner = table.scanner() +scanner.add_predicate(table['ts_val'] == datetime(2017, 1, 1)) + +# Open Scanner and read all tuples +# Note: This doesn't scale for large scans +result = scanner.open().read_all_tuples() +---- + === Spark Integration Known Issues and Limitations - The Kudu Spark integration is tested and developed against Spark 1.6 and Scala
