datalab Python 패키지에서 마이그레이션

datalab Python 패키지는 Cloud Datalab 메모장을 통해 Google Cloud Platform과 상호작용하는 데 사용됩니다. datalab 패키지에는 BigQuery API 메서드를 지원하는 Jupyter 매직과 Python 모듈(예: google.datalab.bigquery)이 포함되어 있습니다.

BigQuery 클라이언트 라이브러리 google-cloud-bigquery는 BigQuery와 상호작용하는 데 사용되는 공식 Python 라이브러리입니다. 이 클라이언트 라이브러리는 pandas DataFrame을 사용한 데이터 전송 및 검색을 가능하게 해주는 함수 및 쿼리 실행을 위한 Jupyter 셀 매직을 제공하며, 모든 BigQuery 기능을 지원합니다. 다음 코드 예에서는 datalab Python 패키지에 이미 익숙한 개발자를 위해 google-cloud-bigquery 라이브러리를 사용하여 일반적인 BigQuery 작업을 수행하는 방법을 보여줍니다.

코드 스니펫에 사용된 라이브러리 버전은 requirements.txt 파일을 참조하세요.

참고: 이 가이드의 datalab은 호스팅되는 메모장 서비스 Cloud Datalab이 아닌 datalab Python 패키지를 참조합니다.

Jupyter 매직 및 셸 명령어 사용

두 라이브러리 모두 셀 매직을 사용하여 BigQuery에 저장된 데이터를 쿼리할 수 있습니다. 매직 접근 방법 측면에서 두 라이브러리의 주요 차이점은 다음과 같습니다.

	datalab	google-cloud-bigquery
매직 이름	bq	bigquery
Jupyter 확장 프로그램 이름(매직을 로드하는 데 사용)	google.datalab.kernel	google.cloud.bigquery
쿼리 실행	쿼리 정의 및 실행을 별도의 단계에서 실행할 수 있습니다.	쿼리는 매직 명령어가 실행될 때 항상 즉시 실행됩니다.
매직이 적용되는 기능	일부 기능은 지원되지 않습니다.	쿼리만 매직을 통해 수행할 수 있습니다. 다른 BigQuery 기능에서는 명령줄 도구 또는 google.cloud.bigquery.Client 메서드를 사용합니다.
쿼리 결과 저장	쿼리 매직을 통해 쿼리 결과를 대상 테이블에 저장할 수 있지만 변수에 저장할 수는 없습니다. 변수에 대한 쿼리 결과를 저장하려면 매직 대신 Python을 사용하여 쿼리를 실행하세요(예시 참조).	쿼리 매직을 통해 쿼리 결과를 변수에 저장할 수 있지만 대상 테이블에는 저장할 수 없습니다. 대상 테이블에 쿼리 결과를 저장하려면 매직 대신 Python을 사용하여 쿼리를 실행하세요(예시 참조).

Python 클라이언트 라이브러리 설치

BigQuery 클라이언트 라이브러리를 pandas DataFrames 작업에 필요한 종속 항목과 함께 설치하려면 메모장에 다음 명령어를 입력하세요.

!pip install --upgrade google-cloud-bigquery[pandas,pyarrow]

참고: 패키지를 설치한 후 커널을 다시 시작해야 할 수도 있습니다.

매직 로드

Jupyter 매직은 최소한의 구문으로 명령어를 실행할 수 있게 해주는 메모장별 바로가기입니다. Jupyter 메모장에는 많은 기본 제공 명령어가 사전에 로드되어 있습니다. datalab 및 google-cloud-python Python 패키지는 Google Cloud Platform과 상호작용하기 위해 Jupyter 메모장에 로드할 수 있는 추가 매직 명령어를 구현합니다(Cloud Datalab 포함).

datalab

datalab 매직은 Cloud Datalab 메모장에 사전 로드됩니다. Jupyter 메모장에 매직을 로드하려면 다음 명령어를 입력하세요.

%load_ext google.datalab.kernel

datalab 라이브러리 소스 저장소에서 더 많은 매직 로드 옵션을 확인할 수 있습니다.

google-cloud-bigquery

BigQuery 매직을 로드하려면 다음 명령어를 입력합니다.

%load_ext google.cloud.bigquery

참고: %load_ext는 Jupyter에 기본 제공되는 여러 매직 명령어 중 하나입니다. %load_ext 및 기타 기본 제공 매직 명령어에 대한 자세한 내용은 Jupyter 문서를 참조하세요.

BigQuery 셀 매직은 google-cloud-bigquery 패키지가 설치된 모든 메모장에서 작동합니다. 셀 매직을 사용하려면 클라이언트 라이브러리 0.32.0 이상을 사용해야 합니다.

쿼리 실행

다음 예에서는 셀 매직을 사용하여 쿼리를 실행하는 방법을 보여줍니다. 두 예 모두 쿼리를 실행하고 입력 셀 아래에 결과를 표시합니다.

datalab

쿼리 결과가 입력 셀 아래에 QueryResultsTable로 표시됩니다.

%%bq query
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
GROUP BY word
ORDER BY count ASC
LIMIT 100

google-cloud-bigquery

쿼리 결과가 입력 셀 아래 pandas DataFrame에 표시됩니다.

%%bigquery
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
GROUP BY word
ORDER BY count ASC
LIMIT 100

쿼리를 실행하고 결과를 변수에 저장

다음 예시에서는 쿼리를 실행하는 방법과 my_variable이라는 변수에 결과를 저장하는 방법을 보여줍니다.

datalab

datalab 쿼리 매직은 --name 또는-n 플래그와 함께 이름을 전달하여 SQL 쿼리를 실행하지 않고도 저장할 수 있습니다.

%%bq query -n my_query
SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
WHERE state = "TX"
LIMIT 100

저장된 쿼리는 별도로 실행 가능하며 결과는 변수에 저장됩니다.

import google.datalab.bigquery as bq

my_variable = my_query.execute().result().to_dataframe()

google-cloud-bigquery

%%bigquery my_variable
SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
WHERE state = "TX"
LIMIT 100

참고: 대상 테이블에 쿼리 결과를 저장하려면 매직 대신 Python을 사용하여 쿼리를 실행하세요(예시 참조).

매개변수화된 쿼리 실행

다음 예에서는 매개변수화된 쿼리를 실행하는 방법을 보여줍니다. 매개변수화된 쿼리를 실행하면 쿼리 매개변수를 정의하고 별도의 셀에서 쿼리를 실행할 수 있습니다. 자세한 내용은 매개변수화된 쿼리 실행을 참조하세요.

datalab

쿼리를 정의합니다.

%%bq query -n my_query
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
WHERE corpus = @corpus_name
GROUP BY word
ORDER BY count ASC
LIMIT @limit

매개변수를 설정합니다.

corpus_name = "hamlet"
limit = 10

쿼리를 실행합니다.

%%bq execute -q my_query --to-dataframe
parameters:
- name: corpus_name
  type: STRING
  value: $corpus_name
- name: limit
  type: INTEGER
  value: $limit

google-cloud-bigquery

매개변수를 정의합니다.

params = {"corpus_name": "hamlet", "limit": 10}

쿼리를 정의하고 실행합니다.

%%bigquery --params $params
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
WHERE corpus = @corpus_name
GROUP BY word
ORDER BY count ASC
LIMIT @limit

추가 명령어

datalab 라이브러리에는 많은 유형의 BigQuery 작업을 위한 매직이 포함되어 있으며 google-cloud-bigquery 라이브러리에는 쿼리 실행을 위한 하나의 셀 매직이 포함되어 있습니다. 쿼리 이외의 작업을 위한 명령어를 실행하려면 BigQuery 명령줄 도구를 사용하세요. 다음 예에서는 datalab 셀 매직 또는 BigQuery 셸 명령어를 사용하여 bigquery-public-data 프로젝트의 samples 데이터세트에 있는 모든 테이블을 나열하는 방법을 보여줍니다.

datalab

%bq tables list --dataset bigquery-public-data.samples

BigQuery 명령줄 도구

Cloud SDK의 일부로 설치되는 BigQuery 명령줄 도구를 시작하려면 Cloud SDK 설치 안내를 따르세요. 메모장의 셸 명령어 앞에는 !를 추가해야 합니다. BigQuery 명령줄 도구가 설정되어 메모장에서 사용할 수 있게 되면 위의 datalab 셀 매직과 동일한 기능을 제공하는 다음 명령어를 입력합니다.

!bq ls bigquery-public-data:samples

참고: 명령어의 첫 문자는 !이며 %가 아닙니다. 이는 매직이 아닌 셸 명령어임을 나타냅니다. 메모장에서 셸 명령어를 실행하는 데 대한 자세한 내용은 IPython 문서를 참조하세요.

전체 명령어 목록을 보려면 다음 명령어를 입력합니다.

!bq help

참고: 여러 Google Cloud 서비스에 사용할 수 있는 명령줄 도구가 있습니다. 예를 들어 gsutil은 메모장 또는 명령줄에서 사용할 수 있는 매직과 비슷한 인터페이스를 제공합니다.

Python 코드 사용

Jupyter 매직 외에, datalab 및 google-cloud-bigquery 패키지의 Python 메서드를 사용하여 BigQuery 작업을 수행할 수도 있습니다.

쿼리 실행

두 라이브러리 모두 쿼리를 실행하고 결과를 pandas DataFrame으로 반환하는 작업을 지원합니다.

datalab

GitHub에서 보기 의견 보내기

import google.datalab.bigquery as bq

sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = "TX"
    LIMIT 100
"""
df = bq.Query(sql).execute().result().to_dataframe()

google-cloud-bigquery

GitHub에서 보기 의견 보내기

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = "TX"
    LIMIT 100
"""
df = client.query(sql).to_dataframe()

BigQuery 테이블로 데이터 로드

다음 예에서는 새 데이터세트를 만들어 Cloud Storage의 CSV 파일에서 새 테이블로 데이터를 로드하는 방법을 보여줍니다.

datalab

GitHub에서 보기 의견 보내기

import google.datalab.bigquery as bq

# Create the dataset
dataset_id = 'import_sample'
bq.Dataset(dataset_id).create()

# Create the table
schema = [
    {'name': 'name', 'type': 'STRING'},
    {'name': 'post_abbr', 'type': 'STRING'},
]
table = bq.Table(
    '{}.us_states'.format(dataset_id)).create(schema=schema)
table.load(
    'gs://cloud-samples-data/bigquery/us-states/us-states.csv',
    mode='append',
    source_format='csv',
    csv_options=bq.CSVOptions(skip_leading_rows=1)
)  # Waits for the job to complete

google-cloud-bigquery

GitHub에서 보기 의견 보내기

from google.cloud import bigquery

client = bigquery.Client(location='US')

# Create the dataset
dataset_id = 'import_sample'
dataset = client.create_dataset(dataset_id)

# Create the table
job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField('name', 'STRING'),
        bigquery.SchemaField('post_abbr', 'STRING')
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV
)
load_job = client.load_table_from_uri(
    'gs://cloud-samples-data/bigquery/us-states/us-states.csv',
    dataset.table('us_states'),
    job_config=job_config
)
load_job.result()  # Waits for table load to complete.

더 많은 BigQuery Python 클라이언트 라이브러리 사용 예시는 Cloud Storage에서 데이터 로드, 로컬 데이터 소스에서 BigQuery로 데이터 로드, BigQuery로 데이터 스트리밍을 참조하세요.

Pandas DataFrame에서 BigQuery 테이블로 로드

다음 예에서는 새 데이터세트를 만들고 pandas DataFrame에서 새 테이블로 데이터를 로드하는 방법을 보여줍니다.

데이터세트 만들기와 같은 특정 BigQuery 작업에는 위치가 필요합니다. google-cloud-bigquery 클라이언트가 초기화될 때 위치가 제공되는 경우 이 위치가 클라이언트로 생성되는 작업, 데이터세트, 테이블의 기본 위치가 됩니다. datalab 라이브러리는 데이터세트 또는 작업 위치를 지정하는 방법을 제공하지 않으며, 이로 인해 예상치 못한 동작이 발생할 수 있습니다. 자세한 내용은 데이터세트 위치를 참조하세요.

datalab

datalab 라이브러리는 pandas DataFrame에서 BigQuery 테이블로 데이터를 로드할 때 스트리밍 삽입을 수행합니다. 이로 인해 쿼리에서 데이터를 사용할 수 있게 되기까지 약간의 시차가 발생할 수 있습니다. 자세한 내용은 BigQuery로 데이터 스트리밍을 참조하세요.

GitHub에서 보기 의견 보내기

import google.datalab.bigquery as bq
import pandas

# Create the dataset
dataset_id = 'import_sample'
bq.Dataset(dataset_id).create()

# Create the table and load the data
dataframe = pandas.DataFrame([
    {'title': 'The Meaning of Life', 'release_year': 1983},
    {'title': 'Monty Python and the Holy Grail', 'release_year': 1975},
    {'title': 'Life of Brian', 'release_year': 1979},
    {
        'title': 'And Now for Something Completely Different',
        'release_year': 1971
    },
])
schema = bq.Schema.from_data(dataframe)
table = bq.Table(
    '{}.monty_python'.format(dataset_id)).create(schema=schema)
table.insert(dataframe)  # Starts steaming insert of data

google-cloud-bigquery

BigQuery 클라이언트 라이브러리는 스트리밍 삽입과 대조적으로 pandas DataFrame을 parquet 형식으로 변환하고 로드 작업을 수행합니다. 로드 작업이 완료되는 즉시 데이터를 사용할 수 있습니다.

GitHub에서 보기 의견 보내기

from google.cloud import bigquery
import pandas

client = bigquery.Client(location='US')

dataset_id = 'import_sample'
dataset = client.create_dataset(dataset_id)

# Create the table and load the data
dataframe = pandas.DataFrame([
    {'title': 'The Meaning of Life', 'release_year': 1983},
    {'title': 'Monty Python and the Holy Grail', 'release_year': 1975},
    {'title': 'Life of Brian', 'release_year': 1979},
    {
        'title': 'And Now for Something Completely Different',
        'release_year': 1971
    },
])
table_ref = dataset.table('monty_python')
load_job = client.load_table_from_dataframe(dataframe, table_ref)
load_job.result()  # Waits for table load to complete.