Skip to content

Commit 6ff91a8

Browse files
dhermesdhermes
committed
Adding Bigtable docs.
1 parent 4c1c2c1 commit 6ff91a8

23 files changed

Lines changed: 1030 additions & 66 deletions

‎docs/bigtable-client-intro.rst‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
Base for Everything
2+
===================
3+
4+
To use the API, the :class:`Client <gcloud.bigtable.client.Client>`
5+
class defines a high-level interface which handles authorization
6+
and creating other objects:
7+
8+
.. code:: python
9+
10+
from gcloud.bigtable.client import Client
11+
client = Client()
12+
13+
Long-lived Defaults
14+
-------------------
15+
16+
When creating a :class:`Client <gcloud.bigtable.client.Client>`, the
17+
``user_agent`` and ``timeout_seconds`` arguments have sensible
18+
defaults
19+
(:data:`DEFAULT_USER_AGENT <gcloud.bigtable.client.DEFAULT_USER_AGENT>` and
20+
:data:`DEFAULT_TIMEOUT_SECONDS <gcloud.bigtable.client.DEFAULT_TIMEOUT_SECONDS>`).
21+
However, you may over-ride them and these will be used throughout all API
22+
requests made with the ``client`` you create.
23+
24+
Authorization
25+
-------------
26+
27+
- For an overview of authentication in ``gcloud-python``,
28+
see :doc:`gcloud-auth`.
29+
30+
- In addition to any authentication configuration, you should also set the
31+
:envvar:`GCLOUD_PROJECT` environment variable for the project you'd like
32+
to interact with. If you are Google App Engine or Google Compute Engine
33+
this will be detected automatically.
34+
35+
- After configuring your environment, create a
36+
:class:`Client <gcloud.storage.client.Client>`
37+
38+
.. code::
39+
40+
>>> from gcloud import bigtable
41+
>>> client = bigtable.Client()
42+
43+
or pass in ``credentials`` and ``project`` explicitly
44+
45+
.. code::
46+
47+
>>> from gcloud import bigtable
48+
>>> client = bigtable.Client(project='my-project', credentials=creds)
49+
50+
.. tip::
51+
52+
Be sure to use the **Project ID**, not the **Project Number**.
53+
54+
Admin API Access
55+
----------------
56+
57+
If you'll be using your client to make `Cluster Admin`_ and `Table Admin`_
58+
API requests, you'll need to pass the ``admin`` argument:
59+
60+
.. code:: python
61+
62+
client = Client(admin=True)
63+
64+
Read-Only Mode
65+
--------------
66+
67+
If on the other hand, you only have (or want) read access to the data,
68+
you can pass the ``read_only`` argument:
69+
70+
.. code:: python
71+
72+
client = Client(read_only=True)
73+
74+
This will ensure that the
75+
:data:`READ_ONLY_SCOPE <gcloud.bigtable.client.READ_ONLY_SCOPE>` is used
76+
for API requests (so any accidental requests that would modify data will
77+
fail).
78+
79+
Next Step
80+
---------
81+
82+
After a :class:`Client <gcloud.bigtable.client.Client>`, the next highest-level
83+
object is a :class:`Cluster <gcloud.bigtable.cluster.Cluster>`. You'll need
84+
one before you can interact with tables or data.
85+
86+
Head next to learn about the :doc:`bigtable-cluster-api`.
87+
88+
.. _Cluster Admin: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/tree/master/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1
89+
.. _Table Admin: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/tree/master/bigtable-protos/src/main/proto/google/bigtable/admin/table/v1

‎docs/bigtable-client.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Client
2+
~~~~~~
3+
4+
.. automodule:: gcloud.bigtable.client
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/bigtable-cluster-api.rst‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
Cluster Admin API
2+
=================
3+
4+
After creating a :class:`Client <gcloud.bigtable.client.Client>`, you can
5+
interact with individual clusters, groups of clusters or available
6+
zones for a project.
7+
8+
List Clusters
9+
-------------
10+
11+
If you want a comprehensive list of all existing clusters, make a
12+
`ListClusters`_ API request with
13+
:meth:`Client.list_clusters() <gcloud.bigtable.client.Client.list_clusters>`:
14+
15+
.. code:: python
16+
17+
clusters = client.list_clusters()
18+
19+
List Zones
20+
----------
21+
22+
If you aren't sure which ``zone`` to create a cluster in, find out
23+
which zones your project has access to with a `ListZones`_ API request
24+
with :meth:`Client.list_zones() <gcloud.bigtable.client.Client.list_zones>`:
25+
26+
.. code:: python
27+
28+
zones = client.list_zones()
29+
30+
You can choose a :class:`string <str>` from among the result to pass to
31+
the :class:`Cluster <gcloud.bigtable.cluster.Cluster>` constructor.
32+
33+
As of right now, the available zones are
34+
35+
.. code:: python
36+
37+
>>> zones
38+
[u'asia-east1-b', u'europe-west1-c', u'us-central1-c', u'us-central1-b']
39+
40+
Cluster Factory
41+
---------------
42+
43+
To create a :class:`Cluster <gcloud.bigtable.cluster.Cluster>` object:
44+
45+
.. code:: python
46+
47+
cluster = client.cluster(zone, cluster_id,
48+
display_name=display_name,
49+
serve_nodes=3)
50+
51+
Both ``display_name`` and ``serve_nodes`` are optional. When not provided,
52+
``display_name`` defaults to the ``cluster_id`` value and ``serve_nodes``
53+
defaults to the minimum allowed: ``3``.
54+
55+
Even if this :class:`Cluster <gcloud.bigtable.cluster.Cluster>` already
56+
has been created with the API, you'll want this object to use as a
57+
parent of a :class:`Table <gcloud.bigtable.table.Table>` just as the
58+
:class:`Client <gcloud.bigtable.client.Client>` is used as the parent of
59+
a :class:`Cluster <gcloud.bigtable.cluster.Cluster>`.
60+
61+
Create a new Cluster
62+
--------------------
63+
64+
After creating the cluster object, make a `CreateCluster`_ API request
65+
with :meth:`create() <gcloud.bigtable.cluster.Cluster.create>`:
66+
67+
.. code:: python
68+
69+
cluster.display_name = 'My very own cluster'
70+
cluster.create()
71+
72+
If you would like more than the minimum number of nodes (``3``) in your cluster:
73+
74+
.. code:: python
75+
76+
cluster.serve_nodes = 10
77+
cluster.create()
78+
79+
Check on Current Operation
80+
--------------------------
81+
82+
.. note::
83+
84+
When modifying a cluster (via a `CreateCluster`_, `UpdateCluster`_ or
85+
`UndeleteCluster`_ request), the Bigtable API will return a long-running
86+
`Operation`_. This will be stored on the object after each of
87+
:meth:`create() <gcloud.bigtable.cluster.Cluster.create>`,
88+
:meth:`update() <gcloud.bigtable.cluster.Cluster.update>` and
89+
:meth:`undelete() <gcloud.bigtable.cluster.Cluster.undelete>` are called.
90+
91+
You can check if a long-running operation (for a
92+
:meth:`create() <gcloud.bigtable.cluster.Cluster.create>`,
93+
:meth:`update() <gcloud.bigtable.cluster.Cluster.update>` or
94+
:meth:`undelete() <gcloud.bigtable.cluster.Cluster.undelete>`) has finished
95+
by making a `GetOperation`_ request with
96+
:meth:`Operation.finished() <gcloud.bigtable.cluster.Operation.finished>`:
97+
98+
.. code:: python
99+
100+
>>> operation = cluster.create()
101+
>>> operation.finished()
102+
True
103+
104+
.. note::
105+
106+
Once an :class:`Operation <gcloud.bigtable.cluster.Operation>` object
107+
has returned :data:`True` from ``finished()``, the object should not
108+
be re-used. Subsequent calls to
109+
:meth:`finished() <gcloud.bigtable.cluster.Operation.finished>`
110+
will result in a :class:`ValueError <exceptions.ValueError>`.
111+
112+
Get metadata for an existing Cluster
113+
------------------------------------
114+
115+
After creating the cluster object, make a `GetCluster`_ API request
116+
with :meth:`reload() <gcloud.bigtable.cluster.Cluster.reload>`:
117+
118+
.. code:: python
119+
120+
cluster.reload()
121+
122+
This will load ``serve_nodes`` and ``display_name`` for the existing
123+
``cluster`` in addition to the ``cluster_id``, ``zone`` and ``project``
124+
already set on the :class:`Cluster <gcloud.bigtable.cluster.Cluster>` object.
125+
126+
Update an existing Cluster
127+
--------------------------
128+
129+
After creating the cluster object, make an `UpdateCluster`_ API request
130+
with :meth:`update() <gcloud.bigtable.cluster.Cluster.update>`:
131+
132+
.. code:: python
133+
134+
client.display_name = 'New display_name'
135+
cluster.update()
136+
137+
Delete an existing Cluster
138+
--------------------------
139+
140+
Make a `DeleteCluster`_ API request with
141+
:meth:`delete() <gcloud.bigtable.cluster.Cluster.delete>`:
142+
143+
.. code:: python
144+
145+
cluster.delete()
146+
147+
Undelete a deleted Cluster
148+
--------------------------
149+
150+
Make an `UndeleteCluster`_ API request with
151+
:meth:`undelete() <gcloud.bigtable.cluster.Cluster.undelete>`:
152+
153+
.. code:: python
154+
155+
cluster.undelete()
156+
157+
Next Step
158+
---------
159+
160+
Now we go down the hierarchy from
161+
:class:`Cluster <gcloud.bigtable.cluster.Cluster>` to a
162+
:class:`Table <gcloud.bigtable.table.Table>`.
163+
164+
Head next to learn about the :doc:`bigtable-table-api`.
165+
166+
.. _Cluster Admin API: https://cloud.google.com/bigtable/docs/creating-cluster
167+
.. _CreateCluster: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L66-L68
168+
.. _GetCluster: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L38-L40
169+
.. _UpdateCluster: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L93-L95
170+
.. _DeleteCluster: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L109-L111
171+
.. _ListZones: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L33-L35
172+
.. _ListClusters: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L44-L46
173+
.. _GetOperation: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/longrunning/operations.proto#L43-L45
174+
.. _UndeleteCluster: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1/bigtable_cluster_service.proto#L126-L128
175+
.. _Operation: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/longrunning/operations.proto#L73-L102

‎docs/bigtable-cluster.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Cluster
2+
~~~~~~~
3+
4+
.. automodule:: gcloud.bigtable.cluster
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

‎docs/bigtable-column-family.rst‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
Column Families
2+
===============
3+
4+
When creating a
5+
:class:`ColumnFamily <gcloud.bigtable.column_family.ColumnFamily>`, it is
6+
possible to set garbage collection rules for expired data.
7+
8+
By setting a rule, cells in the table matching the rule will be deleted
9+
during periodic garbage collection (which executes opportunistically in the
10+
background).
11+
12+
The types
13+
:class:`GarbageCollectionRule <gcloud.bigtable.column_family.GarbageCollectionRule>`,
14+
:class:`GarbageCollectionRuleUnion <gcloud.bigtable.column_family.GarbageCollectionRuleUnion>` and
15+
:class:`GarbageCollectionRuleIntersection <gcloud.bigtable.column_family.GarbageCollectionRuleIntersection>`
16+
can all be used as the optional ``gc_rule`` argument in the
17+
:class:`ColumnFamily <gcloud.bigtable.column_family.ColumnFamily>`
18+
constructor. This value is then used in the
19+
:meth:`create() <gcloud.bigtable.column_family.ColumnFamily.create>` and
20+
:meth:`update() <gcloud.bigtable.column_family.ColumnFamily.update>` methods.
21+
22+
These rules can be nested arbitrarily, with a
23+
:class:`MaxAgeGCRule <gcloud.bigtable.column_family.MaxAgeGCRule>` or
24+
:class:`MaxVersionsGCRule <gcloud.bigtable.column_family.MaxVersionsGCRule>`
25+
at the lowest level of the nesting:
26+
27+
.. code:: python
28+
29+
import datetime
30+
31+
max_age = datetime.timedelta(days=3)
32+
rule1 = MaxAgeGCRule(max_age)
33+
rule2 = MaxVersionsGCRule(1)
34+
35+
# Make a composite that matches anything older than 3 days **AND**
36+
# with more than 1 version.
37+
rule3 = GarbageCollectionIntersection(rules=[rule1, rule2])
38+
39+
# Make another composite that matches our previous intersection
40+
# **OR** anything that has more than 3 versions.
41+
rule4 = GarbageCollectionRule(max_num_versions=3)
42+
rule5 = GarbageCollectionUnion(rules=[rule3, rule4])
43+
44+
----
45+
46+
.. automodule:: gcloud.bigtable.column_family
47+
:members:
48+
:undoc-members:
49+
:show-inheritance:

0 commit comments

Comments
 (0)