Merge pull request #395 from segmentio/repo-sync

repo sync

Author: bot-docsteam

src/connections/storage/catalog/bigquery/index.md

@@ -5,95 +5,96 @@ redirect_from:
   - '/connections/warehouses/catalog/bigquery/'
 ---
 
-Segment's [BigQuery](https://cloud.google.com/bigquery/) connector makes it easy
+Segment's [BigQuery](https://cloud.google.com/bigquery/){:target="_blank"} connector makes it easy
 to load web, mobile, and third-party source data like Salesforce, Zendesk, and
-Google AdWords into a BigQuery data warehouse.  This guide will explain how to
-set up BigQuery and start loading data into it.
+Google AdWords into a BigQuery data warehouse.  When you integrate BigQuery with Segment you get a fully managed data pipeline loaded into a powerful and cost-effective data warehouse.
 
-The Segment warehouse connector runs a periodic ETL (Extract - Transform - Load)
-process to pull raw events and objects and load them into your BigQuery cluster.
-
-Using BigQuery through Segment means you'll get a fully managed data pipeline
-loaded into one of the most powerful and cost-effective data warehouses today.
+The Segment warehouse connector runs a periodic ETL (Extract - Transform - Load) process to pull raw events and objects from your sources and load them into your BigQuery cluster. 
+For more information about the ETL process, including how it works and common ETL use cases, refer to [Google Cloud's ETL documentation](https://cloud.google.com/learn/what-is-etl){:target="_blank"}.
 
 ## Getting Started
 
 To store your Segment data in BigQuery, complete the following steps:
-- [Enable BigQuery for your Google Cloud project](#create-a-project-and-enable-bigquery)
-- [Create a GCP service account for Segment to assume](#create-a-service-account-for-segment)
-- [Create a warehouse in the Segment app](#create-the-warehouse-in-segment)
+1. [Create a project and enable BigQuery](#create-a-project-and-enable-bigquery)
+2. [Create a service account for Segment](#create-a-service-account-for-segment)
+3. [Create the warehouse in Segment](#create-the-warehouse-in-segment)
 
 ### Create a Project and Enable BigQuery
 
-1. Navigate to the [Google Developers Console](https://console.developers.google.com/)
-2. Configure [Cloud Platform](https://console.cloud.google.com/):
-  - If you don't have a project already, [create one](https://support.google.com/cloud/answer/6251787?hl=en&ref_topic=6158848).
-  - If you have an existing project, you will need to [enable the BigQuery API](https://cloud.google.com/bigquery/quickstart-web-ui).
-    Once you've done so, you should see BigQuery in the "Resources" section of Cloud Platform.
-  - **Note:** make sure [billing is enabled](https://support.google.com/cloud/answer/6293499#enable-billing) on your project, or Segment will not be able to write into the cluster.
-3. Copy the project ID. You will need it when you create a warehouse source in the Segment app.
+To create a project and enable BigQuery:
+1. Navigate to the [Google Developers Console](https://console.developers.google.com/){:target="_blank"}.
+2. Configure the [Google Cloud Platform](https://console.cloud.google.com/){:target="_blank"}:
+  - If you don't have a project already, [create one](https://support.google.com/cloud/answer/6251787?hl=en&ref_topic=6158848){:target="_blank"}.
+  - If you have an existing project, [enable the BigQuery API](https://cloud.google.com/bigquery/quickstart-web-ui){:target="_blank"}. Once you've done so, you should see BigQuery in the "Resources" section of Cloud Platform.
+3. Copy the project ID. You'll need it when you create a warehouse source in the Segment app.
 
-### Create a Service Account for Segment
+> note "Enable billing"
+> When you create your project, you must [enable billing](https://support.google.com/cloud/answer/6293499#enable-billing){:target="_blank"} so Segment can write into the cluster.
 
-Refer to [Google Cloud's documentation about service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
-for more information.
+### Create a service account for Segment
 
-1. From the Navigation panel on the left, go to **IAM & admin** > **Service accounts**
-2. Click **Create Service Account** along the top
-3. Enter a name for the service account (for example: "segment-warehouses") and click **Create**
-4. When assigning permissions, make sure to grant the following roles:
+To create a service account for Segment: 
+1. From the Navigation panel on the left, select **IAM & admin** > **Service accounts**.
+2. Click **Create Service Account**.
+3. Enter a name for the service account (for example, `segment-warehouses`) and click **Create**.
+4. Assign the service account the following roles:
     - `BigQuery Data Owner`
     - `BigQuery Job User`
-5. [Create a JSON key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys).
-The downloaded file will be used to create your warehouse in the next section.
+5. [Create a JSON key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys){:target="_blank"}.
+The downloaded file will be used to create your warehouse in the Segment app.
+
+If you have trouble creating a new service account, refer to [Google Cloud's documentation about service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts){:target="_blank"} for more information.
 
 ### Create the Warehouse in Segment
 
-1. In Segment, go to **Workspace** > **Add destination** > Search for "BigQuery"
-2. Select **BigQuery**
-3. Add a name for the destination to the **Name your destination** field
-4. Enter your project ID in the **Project** field
-5. Copy the contents of the credentials (the JSON key) into the **Credentials** field <br/>
-**Optional:** Enter a [region code](https://cloud.google.com/compute/docs/regions-zones/) in the **Location** field (the default will be "US")
-6. Click **Connect**
-7. If Segment can connect with the provided **Project ID** and **Credentials**, a warehouse will be created and your first sync should begin shortly
+To create the warehouse in Segment: 
+1. From the homepage of the Segment app, select **Connections > Add Destination** and search for **BigQuery**.
+2. Click **BigQuery**.
+3. Select the source(s) you'd like to sync with the BigQuery destination, and click **Next**.
+3. Enter a name for your destination in the **Name your destination** field.
+4. Enter your Project ID in the **Project ID** field.
+  <br/>*Optional:* Enter a [region code](https://cloud.google.com/compute/docs/regions-zones/){:target="_blank"} in the **Location** field (the default is *US*.)
+5. Copy the contents of the JSON key that you created for the Segment service account into the **Credentials** field.
+6. Click **Connect**.
+
+If Segment is able to connect to your project, a warehouse will be created and your first sync will begin shortly.
 
-### Schema
+## Schema
 
-BigQuery datasets are broken down into **tables** and **views**. **Tables**
-contain duplicate data, **views** do _not_.
+BigQuery datasets are broken down into [**tables**](#partitioned-tables) and [**views**](#views). **Tables**
+contain duplicate data, **views** do _not_ contain duplicate data.
 
-#### Partitioned Tables
+### Partitioned Tables
 
-The Segment connector takes advantage of [partitioned
-tables](https://cloud.google.com/bigquery/docs/partitioned-tables). Partitioned
-tables allow you to query a subset of data, thus increasing query performance
-and decreasing costs.
+The Segment connector uses [partitioned
+tables](https://cloud.google.com/bigquery/docs/partitioned-tables){:target="_blank"}. Partitioned
+tables allow you to query a subset of data, which increases query performance
+and decreases costs.
 
-To query a full table, you can query like this:
+To query a full table, use the following command:
 
 ```sql
 select *
 from <project-id>.<source-name>.<collection-name>
 ```
 
-To query a specific partitioned table, you can query like this:
+To query a specific partitioned table, use the following command:
 
 
 ```sql
 select *
 from <project-id>.<source-name>.<collection-name>$20160809
 ```
 
-#### Views
+### Views
 
-A [view](https://cloud.google.com/bigquery/querying-data#views) is a virtual
+A [view](https://cloud.google.com/bigquery/querying-data#views){:target="_blank"} is a virtual
 table defined by a SQL query. Segment uses views in the de-duplication process to
-ensure that events that you are querying unique events, and the latest objects
+ensure that events that you are querying are unique events and contain the latest objects
 from third-party data. All Segment views are set up to show information from the last
-60 days. Whenever possible, query from these views.
+60 days. [Segment recommends querying from these views when possible](#use-views) to avoid duplicate events and historical objects.
 
-Views are appended with `_view` , which you can query like this:
+Views are appended with `_view` , which you can query using this format:
 
 ```sql
 select *
@@ -116,22 +117,23 @@ Account.
 Migrate your warehouse from a shared Service Account to a dedicated Service Account 
 by creating a new Service Account using the [Create a Service Account for Segment](#create-a-service-account-for-segment) section.
 Then, head to your warehouse's connection settings and update with the
-**Credentials** you created. Once you've verified that data is loading properly 
+credentials you created. Once you've verified that data is loading properly 
 to your warehouse, [remove access to the shared Service Account](#remove-access-to-the-shared-service-account).
 
 ### Remove access to the shared Service Account
 You can remove access to the shared Service Account 
 (`[email protected]`) using the following instructions:
 
+To remove access to the shared Service Account: 
 1. Create a [new Service Account for Segment](#create-a-service-account-for-segment) using the linked instructions.
 2. Verify that the data is loading into your warehouse. 
-3. Sign in to the [Google Developers Console](https://console.developers.google.com).
+3. Sign in to the [Google Developers Console](https://console.developers.google.com){:target="_blank"}.
 4. Open the IAM & Admin product, and select **IAM**.
 5. From the list of projects, select the project that has BigQuery enabled.
 6. On the project's page, select the **Permissions** tab, and then click **view by PRINCIPALS**. 
 7. Select the checkbox for the `[email protected]` account and then click **Remove** to remove access to this shared Service Account.
 
-For more information about managing IAM access, see Google's documentation, [Manage access to projects, folders, and organization](https://cloud.google.com/iam/docs/granting-changing-revoking-access).
+For more information about managing IAM access, refer to Google's documentation, [Manage access to projects, folders, and organization](https://cloud.google.com/iam/docs/granting-changing-revoking-access){:target="_blank"}.
 
 
 ## Best Practices
@@ -142,35 +144,30 @@ BigQuery charges based on the amount of data scanned by your queries. Views are
 a derived view over your tables that Segment uses for de-duplication of events.
 Therefore, Segment recommends you query a specific view whenever possible to avoid
 duplicate events and historical objects. It's important to note that BigQuery
-views are not cached. 
+views aren't cached.
+  
+> note "Understanding BigQuery views"
+> BigQuery's views are logical views, not materialized views, which means that the query that defines the view is re-executed every time the view is queried. Queries are billed according to the total amount of data in all table fields referenced directly or indirectly by the top-level query.
 
-> BigQuery's views are logical views, not materialized views, which means that
-> the query that defines the view is re-executed every time the view is queried.
-> Queries are billed according to the total amount of data in all table fields
-> referenced directly or indirectly by the top-level query.
-
-To save more money, you can query the view and set a [destination
-table](https://cloud.google.com/bigquery/docs/tables), and then query the
+To save money, you can query the view and set a [destination
+table](https://cloud.google.com/bigquery/docs/tables){:target="_blank"}, and then query the
 destination table.
 
 ### Query structure
 
-If you typically start exploratory data analysis with `SELECT *` consider
+If you start exploratory data analysis with `SELECT *`, consider
 specifying the fields to reduce costs.
 
-See the section on [partitioned tables](#partitioned-tables) for details on
+Refer to the section on [partitioned tables](#partitioned-tables) for details on
 querying sub-sets of tables.
 
 
 ## FAQs
 
 ### I need more than 60 days of data in my views. Can I change the view definition?
 
-Absolutely! You will just need to modify one of the references to 60 in the view
-definition to the number of days of your choosing.
-
-Segment chose 60 days as it suits the needs of most customers. However,
-you're welcome to update the definition of the view as long as the name stays
+Yes! You just need to modify one of the references to `60` in the view
+definition to the number of days of your choosing. You can update the definition of the view as long as the name stays
 the same.
 
 Here is the base query Segment uses when first setting up your views. Included in the base query are the placeholders (`%s.%s.%s`) that you would want to include the project,
@@ -191,38 +188,35 @@ WHERE ROW_NUMBER = 1
 
 BigQuery offers both a scalable, pay-as-you-go pricing plan based on the amount
 of data scanned, or a flat-rate monthly cost. You can learn more about BigQuery
-pricing [here](https://cloud.google.com/bigquery/pricing).
+pricing [on Google Cloud's BigQuery pricing page](https://cloud.google.com/bigquery/pricing){:target="_blank"}.
 
 BigQuery allows you to set up [Cost Controls and
-Alerts](https://cloud.google.com/bigquery/cost-controls) to help control and
-monitor costs. If you want to learn more about what BigQuery will cost you,
-they've provided [this
-calculator](https://cloud.google.com/products/calculator/) to estimate your
+Alerts](https://cloud.google.com/bigquery/cost-controls){:target="_blank"} to help control and
+monitor costs. If you want to learn more about the costs associated with BigQuery,
+Google Cloud provides [a
+calculator](https://cloud.google.com/products/calculator/){:target="_blank"} to estimate your
 costs.
 
 ### How do I query my data in BigQuery?
 
-You can connect to BigQuery using a BI tool like Mode or Looker, or query
+You can connect a BI tool like Mode or Looker to BigQuery, or query
 directly from the BigQuery console.
 
-BigQuery now supports standard SQL, which you can enable using their query UI. 
-This does not work with views, or with a query that uses table range 
+BigQuery supports standard SQL, which you can enable [using Google Cloud's query UI](https://cloud.google.com/bigquery/docs/reference/standard-sql/introduction#changing_from_the_default_dialect){:target="_blank"}. 
+This doesn't work with views, or with a query that uses table range 
 functions.
 
 ### Does Segment support streaming inserts?
 
-Segment's connector does not support streaming inserts at this time. If you have
-a need for streaming data into BigQuery, [contact Segment support](https://segment.com/requests/integrations/).
+Segment's connector doesn't support streaming inserts at this time. If you have
+a need for streaming data into BigQuery, [contact Segment support](https://segment.com/requests/integrations/){:target="_blank"}.
 
 ### Can I customize my sync schedule?
 
 {% include content/warehouse-sync-sched.md %}
 
-![sync schedule image](images/syncsched.png)
-
 ## Troubleshooting
 
-### I'm seeing duplicates in my tables.
+### I see duplicates in my tables.
 
-This behavior is expected. Segment only de-duplicates data in your views. See the
-section on [views](#views) for more details.
+This behavior is expected. Segment only de-duplicates data in your views. Refer to the [schema section](#schema) for more details.