Repository navigation
Document how to construct external tables #773
Description
Is your feature request related to a problem? Please describe.
Currently, the document on creating a table is clear on how to initialize a Table object with a specific fields schema. For example, here is a code snippet from the docs:
However, a challenge I faced with these docs is knowing how to create a Table with, e.g., an ExternalConfig set.
Based on the source for Table / unit tests, is the correct approach using a property setter?:
from google.cloud import bigquery
client bigquery.Client()
table = bigquery.Table(...)
# use property setter
table.external_data_configuration = bigquery.ExternalConfig(...)
# edit: it looks like ExternalConfig also needs to use setters, so might include, e.g..
external_config = bigquery.ExternalConfig("NEWLINE_DELIMITED_JSON")
external_config.source_uris = [...]Describe the solution you'd like
Can we add an example to the docs so that readers learn these two pieces?:
- Table attributes like schema can be set on
__init__(or via setters) - Other Table attributes must be set using setters
It seems like two places users may look for this info is in the Table API doc, and in the usage/tables - creating a table doc. Also, apologies if it's already somewhere in the docs and I missed it 😅.
Describe alternatives you've considered
Since Table can be constructed using .from_api_repr(), I wondered if this is a more common approach for construction? In that case it seems like having a nudge in the docs on using this path for e.g. constructing an external table would be super helpful!
Activity
tswast commentedon Jul 20, 2021
It could also be good to include such a sample here as well: https://cloud.google.com/bigquery/external-table-definition
tswast commentedon Jul 20, 2021
There is a Python sample here: https://cloud.google.com/bigquery/external-data-cloud-storage#python
tswast commentedon Jan 30, 2023
Looks like we already had such a code sample here:
python-bigquery/docs/snippets.py
Line 935 in 35627d1
It appears on cloud.google.com here: https://cloud.google.com/bigquery/docs/external-data-cloud-storage#create_an_external_table
Admittedly, that was a bit difficult for me to find, but it's there. It does need an update, though.
The Python code sample on https://cloud.google.com/bigquery/docs/external-table-definition is a bit misleading, so I propose we remove that one.
tswast commentedon Feb 1, 2023
Move https://github.com/googleapis/python-bigquery/blob/main/samples/create_table_external_data_configuration.py to samples/snippets (and its corresponding test)
Update the region tag. It should be bigquery_query_external_gcs_perm
Update the docs here: https://cloud.google.com/bigquery/docs/external-data-cloud-storage
Delete the old sample from snippets.py
python-bigquery/docs/snippets.py
Line 935 in 35627d1
meredithslota commentedon Aug 17, 2023
PR above addresses (1) and (2) steps in Tim's comment. Edit will reopen PR, there's a few more changes I want to make.
meredithslota commentedon Aug 18, 2023
There are no Python samples in https://cloud.google.com/bigquery/docs/external-table-definition anymore (removed in internal change 506395040). Submitted a new PR to tackle (1) and (2) above.
meredithslota commentedon Sep 16, 2023
Sent cl/565816568 to update the sample location as per (3) above. Pending.
meredithslota commentedon Sep 18, 2023
CL to update sample location now submitted.