이 페이지에서는 BigQuery에서 Spanner 데이터베이스로 통합 쿼리를 실행할 때 Spanner Data Boost를 사용하는 방법을 설명합니다. Data Boost를 사용하면 통합 쿼리가 프로비저닝된 Spanner 인스턴스의 기존 워크로드에 최소한의 영향을 미치면서 실행됩니다. BigQuery에서 Spanner 데이터베이스로의 Data Boost 쿼리는 BigQuery 데이터와 Spanner 데이터를 조인할 수 있습니다.
Spanner 통합을 사용하면 BigQuery에서 데이터를 복사하거나 이동하지 않고도 Spanner에 있는 데이터를 실시간으로 쿼리할 수 있습니다.
Spanner 통합 쿼리에 대한 자세한 내용은 Spanner 통합 쿼리를 참조하세요.
Data Boost에 대한 자세한 내용은 Data Boost 개요를 참조하세요.
이러한 필수 권한을 부여하려면 Cloud
Spanner Database Reader With DataBoost(roles/spanner.databaseReaderWithDataBoost) IAM 역할을 사용하는 것이 좋습니다. Data Boost로 통합 쿼리를 실행해야 하는 모든 사용자에게 이 역할을 추가할 수 있습니다. Spanner의 사전 정의된 역할에 대해 자세히 알아보려면 사전 정의된 역할을 참조하세요. 커스텀 IAM 역할을 만드는 방법을 알아보려면 커스텀 역할 만들기를 참조하세요.
통합 Data Boost 쿼리 실행
BigQuery에서 외부 소스로 Data Boost 쿼리를 실행하려면 외부 소스에 대한 BigQuery 연결과 연결 ID가 필요합니다. Data Boost를 사용하여 통합 Spanner 쿼리를 실행하면 외부 소스는 Spanner 데이터베이스입니다. 연결 ID를 만들면 이는 BigQuery에서 Spanner 데이터베이스의 Data Boost 쿼리를 실행하는데 사용됩니다.
다음 옵션 중 하나를 사용하여 BigQuery 연결 ID를 만든 다음 연결 ID를 사용하여 BigQuery에서 Data Boost 쿼리를 실행합니다.
Spanner에서 시작 - Spanner 콘솔에서 BigQuery 외부 연결 ID를 만듭니다. Spanner 콘솔에서 연결 ID가 생성되면 BigQuery 콘솔로 리디렉션되어 Spanner 데이터베이스에 대한 제휴 Data Boost 쿼리를 실행합니다.
BigQuery에서 시작 - BigQuery 콘솔 또는 bq 명령줄 도구를 사용하여 Data Boost 외부 연결 ID를 만듭니다. 연결 ID를 만든 후 BigQuery 콘솔에 계속 머물러 Spanner 데이터베이스에 대한 제휴 Data Boost 쿼리를 실행합니다.
Spanner에서 시작하여 Data Boost 쿼리 실행
Spanner Studio에서 시작하여 통합 Data Boost 쿼리를 실행하려면 다음 단계를 수행하세요.
연결 ID는 Spanner 데이터베이스에 대한 새 BigQuery 외부 연결을 만드는 데 사용됩니다. 다음 패턴을 사용하여 외부 연결을 참조합니다.
PROJECT-ID.LOCATION.CONNECTION-ID
ID가 이미 존재하는 경우 오류가 발생합니다.
대화상자의 나머지 부분을 작성하고 다음을 수행합니다.
동시에 데이터 읽기를 선택합니다.
Spanner Data Boost 사용을 선택합니다.
BigQuery에서 보기를 클릭합니다.
BigQuery Studio가 다음 쿼리와 함께 열립니다.
SELECT*FROMEXTERNAL_QUERY("PROJECT-ID.LOCATION.CONNECTION-ID","SELECT * FROM INFORMATION_SCHEMA.TABLES;");
이를 통합 쿼리로 대체할 수 있습니다. 예를 들어 다음 예시와 유사한 쿼리를 실행할 수 있습니다. 이 예시에서는 Spanner 데이터베이스의 orders 테이블에서 통합 쿼리를 실행하고 결과를 mydataset.customers라는 BigQuery 테이블과 조인합니다.
SELECTc.customer_id,c.name,rq.first_order_dateFROMmydataset.customersAScLEFTOUTERJOINEXTERNAL_QUERY('my-project.us.example-db','''SELECT customer_id, MIN(order_date) AS first_order_date FROM orders GROUP BY customer_id''')ASrqONrq.customer_id=c.customer_idGROUPBYc.customer_id,c.name,rq.first_order_date;
BigQuery에서 시작하여 Data Boost 쿼리 실행
BigQuery에서 Spanner 데이터베이스로 외부 데이터 연결을 만들고 이 연결을 사용하여 BigQuery에서 제휴 Data Boost 쿼리를 실행하려면 다음 옵션 중 하나를 선택합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-26(UTC)"],[],[],null,["# Run federated queries with Data Boost\n\nThis page explains how to use Spanner Data Boost when you run federated queries\nfrom BigQuery to a Spanner database. With\nData Boost, federated queries run with minimal impact to existing\nworkloads on the provisioned Spanner instance. The\nData Boost queries from BigQuery to a\nSpanner database can join BigQuery data with\nSpanner data.\n\nSpanner federation lets BigQuery query data\nresiding in Spanner in real time, without copying or moving data.\nTo learn more about Spanner federated queries, see [Spanner federated queries](/bigquery/docs/spanner-federated-queries).\nTo learn about Data Boost, see [Data Boost\noverview](/spanner/docs/databoost/databoost-overview).\n\nBefore you begin\n----------------\n\nBefore you can run federated queries with Data Boost, you need to\ncomplete the following tasks:\n\n- [Create a Spanner instance and\n database](#create-instance-database).\n\n- [Enable the BigQuery connection API](#enable-bqconnect-API).\n\n- [Grant the required IAM permissions](#grant-databoost-perms).\n\n### Create a Spanner instance and database\n\nIf you don't have a Spanner instance and database, follow the\nsteps in [Create and query a database using the Google Cloud console](/spanner/docs/create-query-database-console) to create them.\n\n### Enable the BigQuery connection API\n\nThe BigQuery connection API lets you manage\nBigQuery connections to external data sources such as a\nSpanner database.\n\n-\n\n\n Enable the BigQuery connection API.\n\n\n [Enable the API](https://console.cloud.google.com/flows/enableapi?apiid=bigqueryconnection.googleapis.com)\n\n\u003cbr /\u003e\n\nFor more information, see [BigQuery connection\nAPI](/bigquery/docs/reference/bigqueryconnection/rest) in the\nBigQuery documentation.\n\n### Grant IAM permissions for Data Boost to principals\n\nA principal must be granted the following permissions to run federated queries\nwith Data Boost:\n\n- `spanner.instances.get` - lets you get the configuration of an instance.\n- `spanner.databases.useDataBoost` - lets you use the [Spanner Data Boost](/spanner/docs/databoost/databoost-overview) compute resources to process [partitioned queries](/spanner/docs/reads#read_data_in_parallel).\n\nFor more information about Spanner permissions, see [Identity and Access Management\n(IAM) permissions](/spanner/docs/iam#permissions).\n\nTo grant these required permissions, we recommend that you use the `Cloud\nSpanner Database Reader With DataBoost`\n(`roles/spanner.databaseReaderWithDataBoost`) IAM role. You can\nadd that role to any principal that needs to run federated queries\nwith Data Boost. To learn more about predefined roles in\nSpanner, see [Predefined roles](/spanner/docs/iam#roles). To learn\nhow to create a custom IAM role, see [Create a custom\nrole](/iam/docs/creating-custom-roles#creating).\n\nRun a federated Data Boost query\n--------------------------------\n\nTo run a Data Boost query from BigQuery to an\nexternal source, you need a BigQuery connection to the external\nsource and the ID of the connection. When you run a federated\nSpanner query with Data Boost, the external source\nis a Spanner database. After you create your connection ID, it's\nused by BigQuery to run a Data Boost\nquery of a Spanner database.\n\nUse one of the following options to create a BigQuery connection\nID, and then use the connection ID to run a Data Boost query from\nBigQuery:\n\n1. [Start in Spanner](#run-query-from-spanner) - Create the\n BigQuery external connection ID in the Spanner\n console. After your connection ID is created in the Spanner\n console, you're redirected to the BigQuery console to run a\n federated Data Boost query to a Spanner\n database.\n\n2. [Start in BigQuery](#run-query-from-bigquery) - Create the\n Data Boost external connection ID in the\n BigQuery console or using the `bq` command-line tool. After\n you create the connection ID, you stay in the BigQuery\n console to run a federated Data Boost query to a\n Spanner database.\n\n### Start in Spanner to run a Data Boost query\n\nTo run a federated Data Boost query starting in the\nSpanner Studio, do the following:\n\n1. Go to the Spanner **Instances** page in the\n Google Cloud console.\n\n [Go to the Instances page](https://console.cloud.google.com/spanner/instances)\n\n The console shows a list of your Spanner\n instances.\n2. Select a Spanner instance, and then select a database.\n\n3. On the **Database overview** page, in the navigation menu, click\n **Spanner Studio**.\n\n4. Click **View in BiqQuery**.\n\n5. In the **View in BigQuery** dialog, enter a connection ID.\n\n The connection ID is used to create a new BigQuery external\n connection to your Spanner database. You reference your\n external connection using the following pattern: \n\n \u003cvar translate=\"no\"\u003ePROJECT-ID\u003c/var\u003e.\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e.\u003cvar translate=\"no\"\u003eCONNECTION-ID\u003c/var\u003e\n\n An error occurs if the ID already exists.\n6. Fill in the rest of the dialog and do the following:\n\n - Select **Read data in parallel**.\n - Select **Use Spanner Data Boost**.\n7. Click **View in BigQuery**.\n\n BigQuery Studio opens with the following query: \n\n SELECT * FROM EXTERNAL_QUERY(\"\u003cvar translate=\"no\"\u003ePROJECT-ID\u003c/var\u003e.\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e.\u003cvar translate=\"no\"\u003eCONNECTION-ID\u003c/var\u003e\", \"SELECT * FROM INFORMATION_SCHEMA.TABLES;\");\n\n You can replace this with your federated query. For example, you might make\n a query that's similar to the following example. This example makes a\n federated query from a table named `orders` in a Spanner\n database and joins the results with a BigQuery table named\n `mydataset.customers`. \n\n ```sql\n SELECT c.customer_id, c.name, rq.first_order_date\n FROM mydataset.customers AS c\n LEFT OUTER JOIN EXTERNAL_QUERY(\n 'my-project.us.example-db',\n '''SELECT customer_id, MIN(order_date) AS first_order_date\n FROM orders\n GROUP BY customer_id''') AS rq\n ON rq.customer_id = c.customer_id\n GROUP BY c.customer_id, c.name, rq.first_order_date;\n ```\n\n### Start in BigQuery to run a Data Boost query\n\nTo create an external data connection from BigQuery to a\nSpanner database and use that connection to run a federated\nData Boost query from BigQuery, select one of the\nfollowing options: \n\n### Console\n\n1. Go to [Create Spanner connections](/bigquery/docs/connect-to-spanner#create-spanner-connection)\n in the BigQuery documentation and follow the instructions on\n the **Console** tab.\n\n2. In the **External data source** pane, do the following:\n\n - Select **Read data in parallel**.\n - Select **Use Spanner Data Boost**.\n\n### bq\n\n1. Go to [Create Spanner connections](/bigquery/docs/connect-to-spanner#create-spanner-connection)\n in the BigQuery documentation and follow instructions on the\n **bq**\\* tab.\n\n2. Set the following connection properties to `true`:\n\n - `useParallelism`\n - `useDataBoost`\n\nThe following example uses the [`bq\nmk`](/bigquery/docs/reference/bq-cli-reference#bq_mk) command to create a\nnew connection named `my_connection` with the two required properties for\nData Boost: \n\n bq mk --connection --connection_type='CLOUD_SPANNER' --location='us' \\\n --properties='{\"database\":\"projects/my-project/instances/my-instance/databases/my-database\", \"useParallelism\":true, \"useDataBoost\": true}' my_connection\n\nWhat's next\n-----------\n\n- Learn about Data Boost in [Data Boost overview](/spanner/docs/databoost/databoost-overview)\n- [Use Data Boost in your applications](/spanner/docs/databoost/databoost-applications)\n- [Monitor Data Boost usage](/spanner/docs/databoost/databoost-monitor)\n- [Monitor and manage Data Boost quota usage](/spanner/docs/databoost/databoost-quotas)"]]
