Skip to content

Commit 9eda391

Browse files
dhermesdhermes
committed
Adding Bigtable docs.
1 parent 43674b9 commit 9eda391

30 files changed

+1227
-157
lines changed

‎docs/bigtable-client-intro.rst‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
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 can 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. (Setting this environment
34+
variable is not required, you may instead pass the ``project`` explicitly
35+
when constructing a :class:`Client <gcloud.storage.client.Client>`).
36+
37+
- After configuring your environment, create a
38+
:class:`Client <gcloud.storage.client.Client>`
39+
40+
.. code::
41+
42+
>>> from gcloud import bigtable
43+
>>> client = bigtable.Client()
44+
45+
or pass in ``credentials`` and ``project`` explicitly
46+
47+
.. code::
48+
49+
>>> from gcloud import bigtable
50+
>>> client = bigtable.Client(project='my-project', credentials=creds)
51+
52+
.. tip::
53+
54+
Be sure to use the **Project ID**, not the **Project Number**.
55+
56+
Admin API Access
57+
----------------
58+
59+
If you'll be using your client to make `Cluster Admin`_ and `Table Admin`_
60+
API requests, you'll need to pass the ``admin`` argument:
61+
62+
.. code:: python
63+
64+
client = bigtable.Client(admin=True)
65+
66+
Read-Only Mode
67+
--------------
68+
69+
If on the other hand, you only have (or want) read access to the data,
70+
you can pass the ``read_only`` argument:
71+
72+
.. code:: python
73+
74+
client = bigtable.Client(read_only=True)
75+
76+
This will ensure that the
77+
:data:`READ_ONLY_SCOPE <gcloud.bigtable.client.READ_ONLY_SCOPE>` is used
78+
for API requests (so any accidental requests that would modify data will
79+
fail).
80+
81+
Next Step
82+
---------
83+
84+
After a :class:`Client <gcloud.bigtable.client.Client>`, the next highest-level
85+
object is a :class:`Cluster <gcloud.bigtable.cluster.Cluster>`. You'll need
86+
one before you can interact with tables or data.
87+
88+
Head next to learn about the :doc:`bigtable-cluster-api`.
89+
90+
.. _Cluster Admin: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/tree/master/bigtable-protos/src/main/proto/google/bigtable/admin/cluster/v1
91+
.. _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: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
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+
The available zones (as of February 2016) 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:
54+
:data:`DEFAULT_SERVE_NODES <gcloud.bigtable.cluster.DEFAULT_SERVE_NODES>`.
55+
56+
Even if this :class:`Cluster <gcloud.bigtable.cluster.Cluster>` already
57+
has been created with the API, you'll want this object to use as a
58+
parent of a :class:`Table <gcloud.bigtable.table.Table>` just as the
59+
:class:`Client <gcloud.bigtable.client.Client>` is used as the parent of
60+
a :class:`Cluster <gcloud.bigtable.cluster.Cluster>`.
61+
62+
Create a new Cluster
63+
--------------------
64+
65+
After creating the cluster object, make a `CreateCluster`_ API request
66+
with :meth:`create() <gcloud.bigtable.cluster.Cluster.create>`:
67+
68+
.. code:: python
69+
70+
cluster.display_name = 'My very own cluster'
71+
cluster.create()
72+
73+
If you would like more than the minimum number of nodes
74+
(:data:`DEFAULT_SERVE_NODES <gcloud.bigtable.cluster.DEFAULT_SERVE_NODES>`)
75+
in your cluster:
76+
77+
.. code:: python
78+
79+
cluster.serve_nodes = 10
80+
cluster.create()
81+
82+
Check on Current Operation
83+
--------------------------
84+
85+
.. note::
86+
87+
When modifying a cluster (via a `CreateCluster`_, `UpdateCluster`_ or
88+
`UndeleteCluster`_ request), the Bigtable API will return a long-running
89+
`Operation`_. This will be stored on the object after each of
90+
:meth:`create() <gcloud.bigtable.cluster.Cluster.create>`,
91+
:meth:`update() <gcloud.bigtable.cluster.Cluster.update>` and
92+
:meth:`undelete() <gcloud.bigtable.cluster.Cluster.undelete>` are called.
93+
94+
You can check if a long-running operation (for a
95+
:meth:`create() <gcloud.bigtable.cluster.Cluster.create>`,
96+
:meth:`update() <gcloud.bigtable.cluster.Cluster.update>` or
97+
:meth:`undelete() <gcloud.bigtable.cluster.Cluster.undelete>`) has finished
98+
by making a `GetOperation`_ request with
99+
:meth:`Operation.finished() <gcloud.bigtable.cluster.Operation.finished>`:
100+
101+
.. code:: python
102+
103+
>>> operation = cluster.create()
104+
>>> operation.finished()
105+
True
106+
107+
.. note::
108+
109+
Once an :class:`Operation <gcloud.bigtable.cluster.Operation>` object
110+
has returned :data:`True` from
111+
:meth:`finished() <gcloud.bigtable.cluster.Operation.finished>`, the
112+
object should not be re-used. Subsequent calls to
113+
:meth:`finished() <gcloud.bigtable.cluster.Operation.finished>`
114+
will result in a :class:`ValueError <exceptions.ValueError>`.
115+
116+
Get metadata for an existing Cluster
117+
------------------------------------
118+
119+
After creating the cluster object, make a `GetCluster`_ API request
120+
with :meth:`reload() <gcloud.bigtable.cluster.Cluster.reload>`:
121+
122+
.. code:: python
123+
124+
cluster.reload()
125+
126+
This will load ``serve_nodes`` and ``display_name`` for the existing
127+
``cluster`` in addition to the ``cluster_id``, ``zone`` and ``project``
128+
already set on the :class:`Cluster <gcloud.bigtable.cluster.Cluster>` object.
129+
130+
Update an existing Cluster
131+
--------------------------
132+
133+
After creating the cluster object, make an `UpdateCluster`_ API request
134+
with :meth:`update() <gcloud.bigtable.cluster.Cluster.update>`:
135+
136+
.. code:: python
137+
138+
client.display_name = 'New display_name'
139+
cluster.update()
140+
141+
Delete an existing Cluster
142+
--------------------------
143+
144+
Make a `DeleteCluster`_ API request with
145+
:meth:`delete() <gcloud.bigtable.cluster.Cluster.delete>`:
146+
147+
.. code:: python
148+
149+
cluster.delete()
150+
151+
Undelete a deleted Cluster
152+
--------------------------
153+
154+
Make an `UndeleteCluster`_ API request with
155+
:meth:`undelete() <gcloud.bigtable.cluster.Cluster.undelete>`:
156+
157+
.. code:: python
158+
159+
cluster.undelete()
160+
161+
Next Step
162+
---------
163+
164+
Now we go down the hierarchy from
165+
:class:`Cluster <gcloud.bigtable.cluster.Cluster>` to a
166+
:class:`Table <gcloud.bigtable.table.Table>`.
167+
168+
Head next to learn about the :doc:`bigtable-table-api`.
169+
170+
.. _Cluster Admin API: https://cloud.google.com/bigtable/docs/creating-cluster
171+
.. _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
172+
.. _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
173+
.. _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
174+
.. _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
175+
.. _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
176+
.. _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
177+
.. _GetOperation: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/blob/2aae624081f652427052fb652d3ae43d8ac5bf5a/bigtable-protos/src/main/proto/google/longrunning/operations.proto#L43-L45
178+
.. _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
179+
.. _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: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
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:`MaxAgeGCRule <gcloud.bigtable.column_family.MaxAgeGCRule>`,
14+
:class:`MaxVersionsGCRule <gcloud.bigtable.column_family.MaxVersionsGCRule>`,
15+
:class:`GarbageCollectionRuleUnion <gcloud.bigtable.column_family.GarbageCollectionRuleUnion>` and
16+
:class:`GarbageCollectionRuleIntersection <gcloud.bigtable.column_family.GarbageCollectionRuleIntersection>`
17+
can all be used as the optional ``gc_rule`` argument in the
18+
:class:`ColumnFamily <gcloud.bigtable.column_family.ColumnFamily>`
19+
constructor. This value is then used in the
20+
:meth:`create() <gcloud.bigtable.column_family.ColumnFamily.create>` and
21+
:meth:`update() <gcloud.bigtable.column_family.ColumnFamily.update>` methods.
22+
23+
These rules can be nested arbitrarily, with a
24+
:class:`MaxAgeGCRule <gcloud.bigtable.column_family.MaxAgeGCRule>` or
25+
:class:`MaxVersionsGCRule <gcloud.bigtable.column_family.MaxVersionsGCRule>`
26+
at the lowest level of the nesting:
27+
28+
.. code:: python
29+
30+
import datetime
31+
32+
max_age = datetime.timedelta(days=3)
33+
rule1 = MaxAgeGCRule(max_age)
34+
rule2 = MaxVersionsGCRule(1)
35+
36+
# Make a composite that matches anything older than 3 days **AND**
37+
# with more than 1 version.
38+
rule3 = GarbageCollectionIntersection(rules=[rule1, rule2])
39+
40+
# Make another composite that matches our previous intersection
41+
# **OR** anything that has more than 3 versions.
42+
rule4 = GarbageCollectionRule(max_num_versions=3)
43+
rule5 = GarbageCollectionUnion(rules=[rule3, rule4])
44+
45+
----
46+
47+
.. automodule:: gcloud.bigtable.column_family
48+
:members:
49+
:undoc-members:
50+
:show-inheritance:

0 commit comments

Comments
 (0)