メインコンテンツまでスキップ

VarChar フィールド

Zilliz Cloud では、VARCHAR フィールドと TEXT フィールドでテキスト形式のスカラーデータをサポートしています。このページでは、名前、タグ、カテゴリ、外部 ID などの短く上限のある文字列メタデータ向けに設計された VARCHAR について説明します。

エンティティと一緒に格納して返す必要がある、より長いソーステキスト、ドキュメントの一節、記事本文、チケット、ログには、代わりに TEXT フィールドを使用します。値が 65,535 バイトを超える可能性がある場合、またはコレクションスキーマで固定の max_length を設定したくない場合は、TEXT を使用します。詳細については、Text Field を参照してください。

VARCHAR フィールドを定義する際、次の 2 つのパラメーターが必須です。

  • datatype を DataType.VARCHAR に設定します。

  • 各フィールド値に許可される UTF-8 バイト数の上限を定義する max_length を指定します。max_length の有効範囲は 1 から 65,535 です。

バイト数は文字数と異なる場合があります。たとえば、max_length=10 の場合、"abcdefghij" は 10 UTF-8 バイトを使用するため上限内に収まります。文字列 "一二三四五六七八九十" も 10 文字ですが、30 UTF-8 バイトを使用するため上限を超えます。

📘Notes

Zilliz Cloud では、VARCHAR フィールドで NULL 値とデフォルト値をサポートしています。これらの機能を有効にするには、nullable を有効にし、default_value に文字列値を設定します。詳細については、Nullable & Default を参照してください。

VARCHAR フィールドを追加する​

Zilliz Cloud で短く上限のある文字列メタデータを格納するには、コレクションスキーマで VARCHAR フィールドを定義します。以下は、2 つの VARCHAR フィールドを持つコレクションスキーマを定義する例です。

  • varchar_field1: 最大 100 バイトを格納し、NULL 値を許可し、デフォルト値は "Unknown" です。

  • varchar_field2: 最大 200 バイトを格納し、NULL 値を許可しますが、デフォルト値はありません。

📘Notes

スキーマを定義するときに enable_dynamic_field を有効にすると、Zilliz Cloud では事前に定義されていないスカラーフィールドを挿入できます。ただし、これはクエリと管理の複雑さを増し、パフォーマンスに影響する可能性があります。詳細については、Dynamic Field を参照してください。

python
# Import necessary libraries
from pymilvus import MilvusClient, DataType

# Define server address
SERVER_ADDR = "YOUR_CLUSTER_ENDPOINT"

# Create a MilvusClient instance
client = MilvusClient(uri=SERVER_ADDR, token="YOUR_CLUSTER_TOKEN")

# Define the collection schema
schema = client.create_schema(
    auto_id=False,
    enable_dynamic_field=True,
)

# Add `varchar_field1` that supports NULL values with default value "Unknown"
schema.add_field(field_name="varchar_field1", datatype=DataType.VARCHAR, max_length=100, nullable=True, default_value="Unknown")
# Add `varchar_field2` that supports NULL values without default value
schema.add_field(field_name="varchar_field2", datatype=DataType.VARCHAR, max_length=200, nullable=True)
schema.add_field(field_name="pk", datatype=DataType.INT64, is_primary=True)
schema.add_field(field_name="embedding", datatype=DataType.FLOAT_VECTOR, dim=3)

インデックスパラメーターを設定する​

インデックス作成は、検索とクエリのパフォーマンス向上に役立ちます。Zilliz Cloud では、インデックス作成はベクトルフィールドには必須ですが、スカラーフィールドには任意です。

次の例では、ベクトルフィールド embedding とスカラーフィールド varchar_field1 にインデックスを作成し、どちらにも AUTOINDEX インデックスタイプを使用します。このタイプでは、Zilliz Cloud がデータ型に基づいて最適なインデックスを自動的に選択します。各フィールドのインデックスタイプとパラメーターをカスタマイズすることもできます。詳細については、Index Explained を参照してください。

📘Notes

VARCHAR フィールドで LIKE フィルタリングを高速化するために、NGRAM インデックスを構築することもできます。詳細については、NGRAM を参照してください。

python
# Set index params

index_params = client.prepare_index_params()

# Index `varchar_field1` with AUTOINDEX
index_params.add_index(
    field_name="varchar_field1",
    index_type="AUTOINDEX",
    index_name="varchar_index"
)

# Index `embedding` with AUTOINDEX and specify metric_type
index_params.add_index(
    field_name="embedding",
    index_type="AUTOINDEX",  # Use automatic indexing to simplify complex index settings
    metric_type="COSINE"  # Specify similarity metric type, options include L2, COSINE, or IP
)

コレクションを作成する​

スキーマとインデックスを定義したら、文字列フィールドを含むコレクションを作成します。

python
# Create Collection
client.create_collection(
    collection_name="my_collection",
    schema=schema,
    index_params=index_params
)

データを挿入する​

コレクションを作成したら、スキーマに一致するエンティティを挿入します。

python
# Sample data
data = [
    {"varchar_field1": "Product A", "varchar_field2": "High quality product", "pk": 1, "embedding": [0.1, 0.2, 0.3]},
    {"varchar_field1": "Product B", "pk": 2, "embedding": [0.4, 0.5, 0.6]}, # varchar_field2 field is missing, which should be NULL
    {"varchar_field1": None, "varchar_field2": None, "pk": 3, "embedding": [0.2, 0.3, 0.1]},  # `varchar_field1` should default to `Unknown`, `varchar_field2` is NULL
    {"varchar_field1": "Product C", "varchar_field2": None, "pk": 4, "embedding": [0.5, 0.7, 0.2]},  # `varchar_field2` is NULL
    {"varchar_field1": None, "varchar_field2": "Exclusive deal", "pk": 5, "embedding": [0.6, 0.4, 0.8]},  # `varchar_field1` should default to `Unknown`
    {"varchar_field1": "Unknown", "varchar_field2": None, "pk": 6, "embedding": [0.8, 0.5, 0.3]},  # `varchar_field2` is NULL
    {"varchar_field1": "", "varchar_field2": "Best seller", "pk": 7, "embedding": [0.8, 0.5, 0.3]}, # Empty string is not treated as NULL
]

# Insert data
client.insert(
    collection_name="my_collection",
    data=data
)

フィルター式を使用してクエリを実行する​

エンティティを挿入したら、query メソッドを使用して、指定したフィルター式に一致するエンティティを取得します。

varchar_field1 が文字列 "Product A" に一致するエンティティを取得するには、次のようにします。

python
# Filter `varchar_field1` with value "Product A"
filter = 'varchar_field1 == "Product A"'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["varchar_field1", "varchar_field2"]
)

print(res)

# Example output:
# data: [
#     "{'varchar_field1': 'Product A', 'varchar_field2': 'High quality product', 'pk': 1}"
# ]

varchar_field2 が NULL であるエンティティを取得するには、次のようにします。

python
# Filter entities where `varchar_field2` is null
filter = 'varchar_field2 is null'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["varchar_field1", "varchar_field2"]
)

print(res)

# Example output:
# data: [
#     "{'varchar_field1': 'Product B', 'varchar_field2': None, 'pk': 2}",
#     "{'varchar_field1': 'Unknown', 'varchar_field2': None, 'pk': 3}",
#     "{'varchar_field1': 'Product C', 'varchar_field2': None, 'pk': 4}",
#     "{'varchar_field1': 'Unknown', 'varchar_field2': None, 'pk': 6}"
# ]

varchar_field1 の値が "Unknown" であるエンティティを取得するには、次の式を使用します。varchar_field1 のデフォルト値は "Unknown" であるため、期待される結果には、varchar_field1 が明示的に "Unknown" に設定されているエンティティ、または varchar_field1 が NULL に設定されているエンティティが含まれるはずです。

python
# Filter entities with `varchar_field1` with value `Unknown`
filter = 'varchar_field1 == "Unknown"'

res = client.query(
    collection_name="my_collection",
    filter=filter,
    output_fields=["varchar_field1", "varchar_field2"]
)

print(res)

# Example output:
# data: [
#     "{'varchar_field1': 'Unknown', 'varchar_field2': None, 'pk': 3}",
#     "{'varchar_field1': 'Unknown', 'varchar_field2': 'Exclusive deal', 'pk': 5}",
#     "{'varchar_field1': 'Unknown', 'varchar_field2': None, 'pk': 6}"
# ]

フィルター式を使用したベクトル検索​

基本的なスカラーフィールドのフィルタリングに加えて、ベクトル類似検索とスカラーフィールドフィルターを組み合わせることができます。たとえば、次のコードは、ベクトル検索にスカラーフィールドフィルターを追加する方法を示しています。

python
# Search with string filtering

# Filter `varchar_field2` with value "Best seller"
filter = 'varchar_field2 == "Best seller"'

res = client.search(
    collection_name="my_collection",
    data=[[0.3, -0.6, 0.1]],
    limit=5,
    search_params={"params": {"nprobe": 10}},
    output_fields=["varchar_field1", "varchar_field2"],
    filter=filter
)

print(res)

# Example output:
# data: [
#     "[{'id': 7, 'distance': -0.04468163847923279, 'entity': {'varchar_field1': '', 'varchar_field2': 'Best seller'}}]"
# ]
このページは役に立ちましたか？
Ctrl I