Spanner는 무제한 확장성과 보조 인덱스, 강력한 일관성, 스키마, SQL과 같은 관계형 의미론을 결합하여 하나의 쉬운 솔루션으로 99.999%의 가용성을 제공하는 고도로 확장 가능한 데이터베이스입니다.
이 노트북은 Spanner를 사용하여 SpannerLoader와 SpannerDocumentSaver로 langchain 문서를 저장, 로드 및 삭제하는 방법을 다룹니다. GitHub에서 패키지에 대해 자세히 알아보세요. Open In Colab

​
시작하기 전에

이 노트북을 실행하려면 다음을 수행해야 합니다: 이 노트북의 런타임 환경에서 데이터베이스에 대한 액세스를 확인한 후, 다음 값을 입력하고 예제 스크립트를 실행하기 전에 셀을 실행하세요. 
# @markdown Please specify an instance id, a database, and a table for demo purpose.
INSTANCE_ID = "test_instance"  # @param {type:"string"}
DATABASE_ID = "test_database"  # @param {type:"string"}
TABLE_NAME = "test_table"  # @param {type:"string"}

​
🦜🔗 라이브러리 설치

이 통합은 자체 langchain-google-spanner 패키지에 있으므로 설치해야 합니다. 
pip install -upgrade --quiet langchain-google-spanner langchain
Colab 전용: 다음 셀의 주석을 해제하여 커널을 재시작하거나 버튼을 사용하여 커널을 재시작하세요. Vertex AI Workbench의 경우 상단의 버튼을 사용하여 터미널을 재시작할 수 있습니다. 
# # Automatically restart kernel after installs so that your environment can access the new packages
# import IPython

# app = IPython.Application.instance()
# app.kernel.do_shutdown(True)

​
☁ Google Cloud Project 설정

이 노트북 내에서 Google Cloud 리소스를 활용할 수 있도록 Google Cloud 프로젝트를 설정하세요. 프로젝트 ID를 모르는 경우 다음을 시도해보세요:
  • gcloud config list를 실행하세요.
  • gcloud projects list를 실행하세요.
  • 지원 페이지를 참조하세요: 프로젝트 ID 찾기.
# @markdown Please fill in the value below with your Google Cloud project ID and then run the cell.

PROJECT_ID = "my-project-id"  # @param {type:"string"}

# Set the project id
!gcloud config set project {PROJECT_ID}

​
🔐 인증

Google Cloud Project에 액세스하기 위해 이 노트북에 로그인한 IAM 사용자로 Google Cloud에 인증하세요.
  • Colab을 사용하여 이 노트북을 실행하는 경우 아래 셀을 사용하고 계속 진행하세요.
  • Vertex AI Workbench를 사용하는 경우 여기에서 설정 지침을 확인하세요.
from google.colab import auth

auth.authenticate_user()

​
기본 사용법

​
문서 저장

SpannerDocumentSaver.add_documents(<documents>)로 langchain 문서를 저장합니다. SpannerDocumentSaver 클래스를 초기화하려면 다음 3가지가 필요합니다:
  1. instance_id - 데이터를 로드할 Spanner 인스턴스.
  2. database_id - 데이터를 로드할 Spanner 데이터베이스 인스턴스.
  3. table_name - langchain 문서를 저장할 Spanner 데이터베이스 내의 테이블 이름.
from langchain_core.documents import Document
from langchain_google_spanner import SpannerDocumentSaver

test_docs = [
    Document(
        page_content="Apple Granny Smith 150 0.99 1",
        metadata={"fruit_id": 1},
    ),
    Document(
        page_content="Banana Cavendish 200 0.59 0",
        metadata={"fruit_id": 2},
    ),
    Document(
        page_content="Orange Navel 80 1.29 1",
        metadata={"fruit_id": 3},
    ),
]

saver = SpannerDocumentSaver(
    instance_id=INSTANCE_ID,
    database_id=DATABASE_ID,
    table_name=TABLE_NAME,
)
saver.add_documents(test_docs)

​
Spanner에서 문서 쿼리하기

Spanner 테이블에 연결하는 방법에 대한 자세한 내용은 Python SDK 문서를 확인하세요.

​
테이블에서 문서 로드

SpannerLoader.load() 또는 SpannerLoader.lazy_load()로 langchain 문서를 로드합니다. lazy_load는 반복 중에만 데이터베이스를 쿼리하는 generator를 반환합니다. SpannerLoader 클래스를 초기화하려면 다음이 필요합니다:
  1. instance_id - 데이터를 로드할 Spanner 인스턴스.
  2. database_id - 데이터를 로드할 Spanner 데이터베이스 인스턴스.
  3. query - 데이터베이스 dialect의 쿼리.
from langchain_google_spanner import SpannerLoader

query = f"SELECT * from {TABLE_NAME}"
loader = SpannerLoader(
    instance_id=INSTANCE_ID,
    database_id=DATABASE_ID,
    query=query,
)

for doc in loader.lazy_load():
    print(doc)
    break

​
문서 삭제

SpannerDocumentSaver.delete(<documents>)로 테이블에서 langchain 문서 목록을 삭제합니다. 
docs = loader.load()
print("Documents before delete:", docs)

doc = test_docs[0]
saver.delete([doc])
print("Documents after delete:", loader.load())

​
고급 사용법

​
커스텀 client

기본적으로 생성되는 client는 default client입니다. credentials와 project를 명시적으로 전달하려면 커스텀 client를 생성자에 전달할 수 있습니다. 
from google.cloud import spanner
from google.oauth2 import service_account

creds = service_account.Credentials.from_service_account_file("/path/to/key.json")
custom_client = spanner.Client(project="my-project", credentials=creds)
loader = SpannerLoader(
    INSTANCE_ID,
    DATABASE_ID,
    query,
    client=custom_client,
)

​
Document Page Content 및 Metadata 커스터마이징

loader는 특정 데이터 컬럼에서 page content가 있는 Documents 목록을 반환합니다. 다른 모든 데이터 컬럼은 metadata에 추가됩니다. 각 행은 하나의 document가 됩니다.

​
page content 형식 커스터마이징

SpannerLoader는 page_content라는 컬럼이 있다고 가정합니다. 이러한 기본값은 다음과 같이 변경할 수 있습니다: 
custom_content_loader = SpannerLoader(
    INSTANCE_ID, DATABASE_ID, query, content_columns=["custom_content"]
)
여러 컬럼이 지정된 경우, page content의 문자열 형식은 기본적으로 text(공백으로 구분된 문자열 연결)가 됩니다. 사용자가 지정할 수 있는 다른 형식으로는 text, JSON, YAML, CSV가 있습니다.

​
metadata 형식 커스터마이징

SpannerLoader는 JSON 데이터를 저장하는 langchain_metadata라는 metadata 컬럼이 있다고 가정합니다. metadata 컬럼은 기본 dictionary로 사용됩니다. 기본적으로 다른 모든 컬럼 데이터가 추가되며 원래 값을 덮어쓸 수 있습니다. 이러한 기본값은 다음과 같이 변경할 수 있습니다: 
custom_metadata_loader = SpannerLoader(
    INSTANCE_ID, DATABASE_ID, query, metadata_columns=["column1", "column2"]
)

​
JSON metadata 컬럼 이름 커스터마이징

기본적으로 loader는 langchain_metadata를 기본 dictionary로 사용합니다. 이는 Document의 metadata에 대한 기본 dictionary로 사용할 JSON 컬럼을 선택하도록 커스터마이징할 수 있습니다. 
custom_metadata_json_loader = SpannerLoader(
    INSTANCE_ID, DATABASE_ID, query, metadata_json_column="another-json-column"
)

​
커스텀 staleness

기본 staleness는 15초입니다. 이는 더 약한 bound를 지정하여 커스터마이징할 수 있습니다(주어진 timestamp 기준으로 모든 읽기를 수행하거나 과거의 주어진 duration 기준으로 수행). 
import datetime

timestamp = datetime.datetime.utcnow()
custom_timestamp_loader = SpannerLoader(
    INSTANCE_ID,
    DATABASE_ID,
    query,
    staleness=timestamp,
)

duration = 20.0
custom_duration_loader = SpannerLoader(
    INSTANCE_ID,
    DATABASE_ID,
    query,
    staleness=duration,
)

​
data boost 활성화

기본적으로 loader는 추가 비용이 발생하고 추가 IAM 권한이 필요하므로 data boost를 사용하지 않습니다. 그러나 사용자는 이를 활성화할 수 있습니다. 
custom_databoost_loader = SpannerLoader(
    INSTANCE_ID,
    DATABASE_ID,
    query,
    databoost=True,
)

​
커스텀 client

기본적으로 생성되는 client는 default client입니다. credentials와 project를 명시적으로 전달하려면 커스텀 client를 생성자에 전달할 수 있습니다. 
from google.cloud import spanner

custom_client = spanner.Client(project="my-project", credentials=creds)
saver = SpannerDocumentSaver(
    INSTANCE_ID,
    DATABASE_ID,
    TABLE_NAME,
    client=custom_client,
)

​
SpannerDocumentSaver의 커스텀 초기화

SpannerDocumentSaver는 커스텀 초기화를 허용합니다. 이를 통해 사용자는 Document가 테이블에 저장되는 방식을 지정할 수 있습니다. content_column: Document의 page content에 대한 컬럼 이름으로 사용됩니다. 기본값은 page_content입니다. metadata_columns: 이러한 metadata는 Document의 metadata에 키가 존재하는 경우 특정 컬럼에 저장됩니다. metadata_json_column: 특수 JSON 컬럼의 컬럼 이름입니다. 기본값은 langchain_metadata입니다. 
custom_saver = SpannerDocumentSaver(
    INSTANCE_ID,
    DATABASE_ID,
    TABLE_NAME,
    content_column="my-content",
    metadata_columns=["foo"],
    metadata_json_column="my-special-json-column",
)

​
Spanner의 커스텀 스키마 초기화

SpannerDocumentSaver에는 커스텀 스키마로 문서를 저장할 새 테이블을 생성하는 init_document_table 메서드가 있습니다. 
from langchain_google_spanner import Column

new_table_name = "my_new_table"

SpannerDocumentSaver.init_document_table(
    INSTANCE_ID,
    DATABASE_ID,
    new_table_name,
    content_column="my-page-content",
    metadata_columns=[
        Column("category", "STRING(36)", True),
        Column("price", "FLOAT64", False),
    ],
)
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I