diff --git a/bigquery/README.rst b/bigquery/README.rst index 0e0110136eb4..0ea938e306fe 100644 --- a/bigquery/README.rst +++ b/bigquery/README.rst @@ -74,56 +74,15 @@ Windows Example Usage ------------- -Create a dataset -~~~~~~~~~~~~~~~~ +Perform a query +~~~~~~~~~~~~~~~ .. code:: python from google.cloud import bigquery - from google.cloud.bigquery import Dataset client = bigquery.Client() - dataset_ref = client.dataset('dataset_name') - dataset = Dataset(dataset_ref) - dataset.description = 'my dataset' - dataset = client.create_dataset(dataset) # API request - -Load data from CSV -~~~~~~~~~~~~~~~~~~ - -.. code:: python - - import csv - - from google.cloud import bigquery - from google.cloud.bigquery import LoadJobConfig - from google.cloud.bigquery import SchemaField - - client = bigquery.Client() - - SCHEMA = [ - SchemaField('full_name', 'STRING', mode='required'), - SchemaField('age', 'INTEGER', mode='required'), - ] - table_ref = client.dataset('dataset_name').table('table_name') - - load_config = LoadJobConfig() - load_config.skip_leading_rows = 1 - load_config.schema = SCHEMA - - # Contents of csv_file.csv: - # Name,Age - # Tim,99 - with open('csv_file.csv', 'rb') as readable: - client.load_table_from_file( - readable, table_ref, job_config=load_config) # API request - -Perform a query -~~~~~~~~~~~~~~~ - -.. code:: python - # Perform a query. QUERY = ( 'SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` ' diff --git a/bigquery/docs/index.rst b/bigquery/docs/index.rst index d24621c246f7..99977545436d 100644 --- a/bigquery/docs/index.rst +++ b/bigquery/docs/index.rst @@ -1,408 +1,13 @@ .. include:: /../bigquery/README.rst -Using the Library ------------------ +More Examples +~~~~~~~~~~~~~ -Projects -~~~~~~~~ - -A project is the top-level container in the ``BigQuery`` API: it is tied -closely to billing, and can provide default access control across all its -datasets. If no ``project`` is passed to the client container, the library -attempts to infer a project using the environment (including explicit -environment variables, GAE, and GCE). - -To override the project inferred from the environment, pass an explicit -``project`` to the constructor, or to either of the alternative -``classmethod`` factories: - -.. code-block:: python - - from google.cloud import bigquery - client = bigquery.Client(project='PROJECT_ID') - - -Project ACLs -^^^^^^^^^^^^ - -Each project has an access control list granting reader / writer / owner -permission to one or more entities. This list cannot be queried or set -via the API; it must be managed using the Google Developer Console. - - -Datasets -~~~~~~~~ - -A dataset represents a collection of tables, and applies several default -policies to tables as they are created: - -- An access control list (ACL). When created, a dataset has an ACL - which maps to the ACL inherited from its project. - -- A default table expiration period. If set, tables created within the - dataset will have the value as their expiration period. - -See BigQuery documentation for more information on -`Datasets `_. - - -Dataset operations -^^^^^^^^^^^^^^^^^^ - -List datasets for the client's project: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_list_datasets] - :end-before: [END bigquery_list_datasets] - -Create a new dataset for the client's project: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_create_dataset] - :end-before: [END bigquery_create_dataset] - -Refresh metadata for a dataset (to pick up changes made by another client): - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_get_dataset] - :end-before: [END bigquery_get_dataset] - -Update a property in a dataset's metadata: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_update_dataset_description] - :end-before: [END bigquery_update_dataset_description] - -Modify user permissions on a dataset: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_update_dataset_access] - :end-before: [END bigquery_update_dataset_access] - -Delete a dataset: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_delete_dataset] - :end-before: [END bigquery_delete_dataset] - - -Tables -~~~~~~ - -Tables exist within datasets. See BigQuery documentation for more information -on `Tables `_. - -Table operations -^^^^^^^^^^^^^^^^ -List tables for the dataset: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_list_tables] - :end-before: [END bigquery_list_tables] - -Create a table: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_create_table] - :end-before: [END bigquery_create_table] - -Get a table: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_get_table] - :end-before: [END bigquery_get_table] - -Update a property in a table's metadata: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_update_table_description] - :end-before: [END bigquery_update_table_description] - -Browse selected rows in a table: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_browse_table] - :end-before: [END bigquery_browse_table] - -Insert rows into a table's data: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_table_insert_rows] - :end-before: [END bigquery_table_insert_rows] - -Copy a table: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_copy_table] - :end-before: [END bigquery_copy_table] - -Extract a table to Google Cloud Storage: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_extract_table] - :end-before: [END bigquery_extract_table] - -Delete a table: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_delete_table] - :end-before: [END bigquery_delete_table] - -Upload table data from a file: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_load_from_file] - :end-before: [END bigquery_load_from_file] - -Load table data from Google Cloud Storage -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -See also: `Loading JSON data from Cloud Storage -`_. - -Load a CSV file from Cloud Storage: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_load_table_gcs_csv] - :end-before: [END bigquery_load_table_gcs_csv] - -Load a JSON file from Cloud Storage: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_load_table_gcs_json] - :end-before: [END bigquery_load_table_gcs_json] - -Load a Parquet file from Cloud Storage: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_load_table_gcs_parquet] - :end-before: [END bigquery_load_table_gcs_parquet] - -Customer Managed Encryption Keys -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Table data is always encrypted at rest, but BigQuery also provides a way for -you to control what keys it uses to encrypt they data. See `Protecting data -with Cloud KMS keys -`_ -in the BigQuery documentation for more details. - -Create a new table, using a customer-managed encryption key from -Cloud KMS to encrypt it. - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_create_table_cmek] - :end-before: [END bigquery_create_table_cmek] - -Change the key used to encrypt a table. - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_update_table_cmek] - :end-before: [END bigquery_update_table_cmek] - -Load a file from Cloud Storage, using a customer-managed encryption key from -Cloud KMS for the destination table. - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_load_table_gcs_json_cmek] - :end-before: [END bigquery_load_table_gcs_json_cmek] - -Copy a table, using a customer-managed encryption key from Cloud KMS for the -destination table. - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_copy_table_cmek] - :end-before: [END bigquery_copy_table_cmek] - -Write query results to a table, using a customer-managed encryption key from -Cloud KMS for the destination table. - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_query_destination_table_cmek] - :end-before: [END bigquery_query_destination_table_cmek] - -Queries -~~~~~~~ - - -Querying data -^^^^^^^^^^^^^ - -Run a query and wait for it to finish: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_query] - :end-before: [END bigquery_query] - - -Run a dry run query -^^^^^^^^^^^^^^^^^^^ - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_query_dry_run] - :end-before: [END bigquery_query_dry_run] - - -Writing query results to a destination table -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -See BigQuery documentation for more information on -`writing query results `_. - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_query_destination_table] - :end-before: [END bigquery_query_destination_table] - - -Run a query using a named query parameter -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -See BigQuery documentation for more information on -`parameterized queries `_. - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_query_params_named] - :end-before: [END bigquery_query_params_named] - - -Jobs -~~~~ - -List jobs for a project -^^^^^^^^^^^^^^^^^^^^^^^ - -Jobs describe actions performed on data in BigQuery tables: - -- Load data into a table -- Run a query against data in one or more tables -- Extract data from a table -- Copy a table - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_list_jobs] - :end-before: [END bigquery_list_jobs] - - -Using BigQuery with Pandas -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Retrieve BigQuery data as a Pandas DataFrame -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As of version 0.29.0, you can use the -:func:`~google.cloud.bigquery.table.RowIterator.to_dataframe` function to -retrieve query results or table rows as a :class:`pandas.DataFrame`. - -First, ensure that the :mod:`pandas` library is installed by running: - -.. code-block:: bash - - pip install --upgrade pandas - -Alternatively, you can install the BigQuery python client library with -:mod:`pandas` by running: - -.. code-block:: bash - - pip install --upgrade google-cloud-bigquery[pandas] - -To retrieve query results as a :class:`pandas.DataFrame`: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_query_results_dataframe] - :end-before: [END bigquery_query_results_dataframe] - -To retrieve table rows as a :class:`pandas.DataFrame`: - -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_list_rows_dataframe] - :end-before: [END bigquery_list_rows_dataframe] - -Load a Pandas DataFrame to a BigQuery Table -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As of version 1.3.0, you can use the -:func:`~google.cloud.bigquery.client.Client.load_table_from_dataframe` function -to load data from a :class:`pandas.DataFrame` to a -:class:`~google.cloud.bigquery.table.Table`. To use this function, in addition -to :mod:`pandas`, you will need to install the :mod:`pyarrow` library. You can -install the BigQuery python client library with :mod:`pandas` and -:mod:`pyarrow` by running: - -.. code-block:: bash - - pip install --upgrade google-cloud-bigquery[pandas,pyarrow] - -The following example demonstrates how to create a :class:`pandas.DataFrame` -and load it into a new table: +.. toctree:: + :maxdepth: 2 -.. literalinclude:: snippets.py - :language: python - :dedent: 4 - :start-after: [START bigquery_load_table_dataframe] - :end-before: [END bigquery_load_table_dataframe] + usage/index + Official Google BigQuery How-to Guides API Reference ------------- diff --git a/bigquery/docs/usage.html b/bigquery/docs/usage.html index 9b81d6976cda..78dc14b9ca03 100644 --- a/bigquery/docs/usage.html +++ b/bigquery/docs/usage.html @@ -1,8 +1,8 @@ - + diff --git a/bigquery/docs/usage/client.rst b/bigquery/docs/usage/client.rst new file mode 100644 index 000000000000..d631585ea2fe --- /dev/null +++ b/bigquery/docs/usage/client.rst @@ -0,0 +1,25 @@ +Creating a Client +~~~~~~~~~~~~~~~~~ + +A project is the top-level container in the ``BigQuery`` API: it is tied +closely to billing, and can provide default access control across all its +datasets. If no ``project`` is passed to the client container, the library +attempts to infer a project using the environment (including explicit +environment variables, GAE, and GCE). + +To override the project inferred from the environment, pass an explicit +``project`` to the :class:`~google.cloud.bigquery.client.Client` constructor, +or to either of the alternative ``classmethod`` factories: + +.. code-block:: python + + from google.cloud import bigquery + client = bigquery.Client(project='PROJECT_ID') + + +Project ACLs +^^^^^^^^^^^^ + +Each project has an access control list granting reader / writer / owner +permission to one or more entities. This list cannot be queried or set +via the API; it must be managed using the Google Developer Console. diff --git a/bigquery/docs/usage/datasets.rst b/bigquery/docs/usage/datasets.rst new file mode 100644 index 000000000000..09ae90767cdc --- /dev/null +++ b/bigquery/docs/usage/datasets.rst @@ -0,0 +1,83 @@ +Managing Datasets +~~~~~~~~~~~~~~~~~ + +A dataset represents a collection of tables, and applies several default +policies to tables as they are created: + +- An access control list (ACL). When created, a dataset has an ACL + which maps to the ACL inherited from its project. + +- A default table expiration period. If set, tables created within the + dataset will have the value as their expiration period. + +See BigQuery documentation for more information on +`Datasets `_. + +Listing Datasets +^^^^^^^^^^^^^^^^ + +List datasets for a project with the +:func:`~google.cloud.bigquery.client.Client.list_datasets` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_list_datasets] + :end-before: [END bigquery_list_datasets] + +Getting a Dataset +^^^^^^^^^^^^^^^^^ + +Get a dataset resource (to pick up changes made by another client) with the +:func:`~google.cloud.bigquery.client.Client.get_dataset` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_get_dataset] + :end-before: [END bigquery_get_dataset] + +Creating a Dataset +^^^^^^^^^^^^^^^^^^ + +Create a new dataset with the +:func:`~google.cloud.bigquery.client.Client.create_dataset` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_create_dataset] + :end-before: [END bigquery_create_dataset] + +Updating a Dataset +^^^^^^^^^^^^^^^^^^ + +Update a property in a dataset's metadata with the +:func:`~google.cloud.bigquery.client.Client.update_dataset` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_update_dataset_description] + :end-before: [END bigquery_update_dataset_description] + +Modify user permissions on a dataset with the +:func:`~google.cloud.bigquery.client.Client.update_dataset` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_update_dataset_access] + :end-before: [END bigquery_update_dataset_access] + +Deleting a Dataset +^^^^^^^^^^^^^^^^^^ + +Delete a dataset with the +:func:`~google.cloud.bigquery.client.Client.delete_dataset` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_delete_dataset] + :end-before: [END bigquery_delete_dataset] diff --git a/bigquery/docs/usage/encryption.rst b/bigquery/docs/usage/encryption.rst new file mode 100644 index 000000000000..88d23067995e --- /dev/null +++ b/bigquery/docs/usage/encryption.rst @@ -0,0 +1,52 @@ +Using Customer Managed Encryption Keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Table data is always encrypted at rest, but BigQuery also provides a way for +you to control what keys it uses to encrypt they data. See `Protecting data +with Cloud KMS keys +`_ +in the BigQuery documentation for more details. + +Create a new table, using a customer-managed encryption key from +Cloud KMS to encrypt it. + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_create_table_cmek] + :end-before: [END bigquery_create_table_cmek] + +Change the key used to encrypt a table. + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_update_table_cmek] + :end-before: [END bigquery_update_table_cmek] + +Load a file from Cloud Storage, using a customer-managed encryption key from +Cloud KMS for the destination table. + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_load_table_gcs_json_cmek] + :end-before: [END bigquery_load_table_gcs_json_cmek] + +Copy a table, using a customer-managed encryption key from Cloud KMS for the +destination table. + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_copy_table_cmek] + :end-before: [END bigquery_copy_table_cmek] + +Write query results to a table, using a customer-managed encryption key from +Cloud KMS for the destination table. + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_query_destination_table_cmek] + :end-before: [END bigquery_query_destination_table_cmek] diff --git a/bigquery/docs/usage/index.rst b/bigquery/docs/usage/index.rst new file mode 100644 index 000000000000..ff4c9d7f1a8f --- /dev/null +++ b/bigquery/docs/usage/index.rst @@ -0,0 +1,35 @@ +Usage Guides +~~~~~~~~~~~~ + +BigQuery Basics +^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + client + queries + +Working with BigQuery Resources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + datasets + tables + encryption + jobs + +Integrations with Other Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. toctree:: + :maxdepth: 1 + + pandas + +See also, the :mod:`google.cloud.bigquery.magics` module for integrations +with Jupyter. + + diff --git a/bigquery/docs/usage/jobs.rst b/bigquery/docs/usage/jobs.rst new file mode 100644 index 000000000000..914d1d459ee7 --- /dev/null +++ b/bigquery/docs/usage/jobs.rst @@ -0,0 +1,18 @@ +Managing Jobs +~~~~~~~~~~~~~ + +List jobs for a project +^^^^^^^^^^^^^^^^^^^^^^^ + +Jobs describe actions performed on data in BigQuery tables: + +- Load data into a table +- Run a query against data in one or more tables +- Extract data from a table +- Copy a table + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_list_jobs] + :end-before: [END bigquery_list_jobs] diff --git a/bigquery/docs/usage/pandas.rst b/bigquery/docs/usage/pandas.rst new file mode 100644 index 000000000000..9504bd19673a --- /dev/null +++ b/bigquery/docs/usage/pandas.rst @@ -0,0 +1,62 @@ +Using BigQuery with Pandas +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Retrieve BigQuery data as a Pandas DataFrame +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As of version 0.29.0, you can use the +:func:`~google.cloud.bigquery.table.RowIterator.to_dataframe` function to +retrieve query results or table rows as a :class:`pandas.DataFrame`. + +First, ensure that the :mod:`pandas` library is installed by running: + +.. code-block:: bash + + pip install --upgrade pandas + +Alternatively, you can install the BigQuery python client library with +:mod:`pandas` by running: + +.. code-block:: bash + + pip install --upgrade google-cloud-bigquery[pandas] + +To retrieve query results as a :class:`pandas.DataFrame`: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_query_results_dataframe] + :end-before: [END bigquery_query_results_dataframe] + +To retrieve table rows as a :class:`pandas.DataFrame`: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_list_rows_dataframe] + :end-before: [END bigquery_list_rows_dataframe] + +Load a Pandas DataFrame to a BigQuery Table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As of version 1.3.0, you can use the +:func:`~google.cloud.bigquery.client.Client.load_table_from_dataframe` function +to load data from a :class:`pandas.DataFrame` to a +:class:`~google.cloud.bigquery.table.Table`. To use this function, in addition +to :mod:`pandas`, you will need to install the :mod:`pyarrow` library. You can +install the BigQuery python client library with :mod:`pandas` and +:mod:`pyarrow` by running: + +.. code-block:: bash + + pip install --upgrade google-cloud-bigquery[pandas,pyarrow] + +The following example demonstrates how to create a :class:`pandas.DataFrame` +and load it into a new table: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_load_table_dataframe] + :end-before: [END bigquery_load_table_dataframe] diff --git a/bigquery/docs/usage/queries.rst b/bigquery/docs/usage/queries.rst new file mode 100644 index 000000000000..fc77bb5b80cd --- /dev/null +++ b/bigquery/docs/usage/queries.rst @@ -0,0 +1,49 @@ +Running Queries +~~~~~~~~~~~~~~~ + +Querying data +^^^^^^^^^^^^^ + +Run a query and wait for it to finish: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_query] + :end-before: [END bigquery_query] + + +Run a dry run query +^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_query_dry_run] + :end-before: [END bigquery_query_dry_run] + + +Writing query results to a destination table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +See BigQuery documentation for more information on +`writing query results `_. + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_query_destination_table] + :end-before: [END bigquery_query_destination_table] + + +Run a query using a named query parameter +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +See BigQuery documentation for more information on +`parameterized queries `_. + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_query_params_named] + :end-before: [END bigquery_query_params_named] diff --git a/bigquery/docs/usage/tables.rst b/bigquery/docs/usage/tables.rst new file mode 100644 index 000000000000..555366fd2a4b --- /dev/null +++ b/bigquery/docs/usage/tables.rst @@ -0,0 +1,147 @@ +Managing Tables +~~~~~~~~~~~~~~~ + +Tables exist within datasets. See BigQuery documentation for more information +on `Tables `_. + +Listing Tables +^^^^^^^^^^^^^^ + +List the tables belonging to a dataset with the +:func:`~google.cloud.bigquery.client.Client.list_tables` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_list_tables] + :end-before: [END bigquery_list_tables] + +Getting a Table +^^^^^^^^^^^^^^^ + +Get a table resource with the +:func:`~google.cloud.bigquery.client.Client.get_table` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_get_table] + :end-before: [END bigquery_get_table] + +Browse data rows in a table with the +:func:`~google.cloud.bigquery.client.Client.list_rows` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_browse_table] + :end-before: [END bigquery_browse_table] + +Creating a Table +^^^^^^^^^^^^^^^^ + +Create an empty table with the +:func:`~google.cloud.bigquery.client.Client.create_table` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_create_table] + :end-before: [END bigquery_create_table] + +Load table data from a file with the +:func:`~google.cloud.bigquery.client.Client.load_table_from_file` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_load_from_file] + :end-before: [END bigquery_load_from_file] + +Load a CSV file from Cloud Storage with the +:func:`~google.cloud.bigquery.client.Client.load_table_from_uri` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_load_table_gcs_csv] + :end-before: [END bigquery_load_table_gcs_csv] + +See also: `Loading CSV data from Cloud Storage +`_. + +Load a JSON file from Cloud Storage: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_load_table_gcs_json] + :end-before: [END bigquery_load_table_gcs_json] + +See also: `Loading JSON data from Cloud Storage +`_. + +Load a Parquet file from Cloud Storage: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_load_table_gcs_parquet] + :end-before: [END bigquery_load_table_gcs_parquet] + +See also: `Loading Parquet data from Cloud Storage +`_. + +Updating a Table +^^^^^^^^^^^^^^^^ + +Update a property in a table's metadata with the +:func:`~google.cloud.bigquery.client.Client.update_table` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_update_table_description] + :end-before: [END bigquery_update_table_description] + +Insert rows into a table's data with the +:func:`~google.cloud.bigquery.client.Client.insert_rows` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_table_insert_rows] + :end-before: [END bigquery_table_insert_rows] + +Copying a Table +^^^^^^^^^^^^^^^ + +Copy a table with the +:func:`~google.cloud.bigquery.client.Client.copy_table` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_copy_table] + :end-before: [END bigquery_copy_table] + +Copy table data to Google Cloud Storage with the +:func:`~google.cloud.bigquery.client.Client.extract_table` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_extract_table] + :end-before: [END bigquery_extract_table] + +Deleting a Table +^^^^^^^^^^^^^^^^ + +Delete a table with the +:func:`~google.cloud.bigquery.client.Client.delete_table` method: + +.. literalinclude:: ../snippets.py + :language: python + :dedent: 4 + :start-after: [START bigquery_delete_table] + :end-before: [END bigquery_delete_table]