حقل TIMESTAMPTZCompatible with Milvus 2.6.6+

تحتاج التطبيقات التي تتعقب الوقت عبر المناطق، مثل أنظمة التجارة الإلكترونية أو أدوات التعاون أو التسجيل الموزع، إلى معالجة دقيقة للطوابع الزمنية مع المناطق الزمنية. يوفر نوع البيانات TIMESTAMPTZ في Milvus هذه الإمكانية من خلال تخزين الطوابع الزمنية مع المنطقة الزمنية المرتبطة بها.

ما هو حقل TIMESTAMPTZ؟

حقل TIMESTAMPTZ هو نوع بيانات محدد في المخطط (DataType.TIMESTAMPTZ) في Milvus يعالج المدخلات التي تراعي المناطق الزمنية ويخزن جميع النقاط الزمنية داخليًا كوقت مطلق بتوقيت UTC:

• تنسيق الإدخال المقبول: سلاسل ISO 8601 مع إزاحة المنطقة الزمنية (على سبيل المثال، يشير "2025-05-01T23:59:59+08:00" إلى الساعة 11:59:59 مساءً في 1 مايو 2025 (UTC+08:00)).

• التخزين الداخلي: يتم توحيد جميع قيم TIMESTAMPTZ وتخزينها بالتوقيت العالمي المنسق (UTC).

• المقارنة والتصفية: تُجرى جميع عمليات التصفية والترتيب بالتوقيت العالمي المنسق (UTC)، مما يضمن نتائج متسقة ويمكن التنبؤ بها عبر المناطق الزمنية المختلفة.

العمليات الأساسية

يعكس سير العمل الأساسي لاستخدام حقل TIMESTAMPTZ الحقول العددية الأخرى في Milvus: تعريف الحقل → إدراج البيانات → الاستعلام/التصفية.

الخطوة 1: تعريف حقل TIMESTAMPTZ

لاستخدام حقل « TIMESTAMPTZ »، قم بتعريفه صراحةً في مخطط المجموعة عند إنشاء المجموعة. يوضح المثال التالي كيفية إنشاء مجموعة تحتوي على حقل « tsz » من النوع « DataType.TIMESTAMPTZ ».

import time
from pymilvus import MilvusClient, DataType
import datetime
import pytz

server_address = "http://localhost:19530"
collection_name = "timestamptz_test123"

client = MilvusClient(uri=server_address)

if client.has_collection(collection_name):
    client.drop_collection(collection_name)

schema = client.create_schema()
# Add a primary key field
schema.add_field("id", DataType.INT64, is_primary=True)
# Add a TIMESTAMPTZ field that allows null values
schema.add_field("tsz", DataType.TIMESTAMPTZ, nullable=True)
# Add a vector field
schema.add_field("vec", DataType.FLOAT_VECTOR, dim=4)

client.create_collection(collection_name, schema=schema, consistency_level="Session")
print(f"Collection '{collection_name}' with a TimestampTz field created successfully.")

// java

// nodejs

// go

# restful

الخطوة 2: إدراج البيانات

أدخل كيانات تحتوي على سلاسل نصية بتنسيق ISO 8601 مع إزاحات المنطقة الزمنية.

يُدرج المثال أدناه 8,193 صفًا من البيانات النموذجية في المجموعة. يتضمن كل صف:

• معرفًا فريدًا

• طابع زمني يراعي المنطقة الزمنية (توقيت شنغهاي)

• متجه بسيط رباعي الأبعاد

data_size = 8193

# Get the Asia/Shanghai time zone using the pytz library
# You can use any valid IANA time zone identifier such as:
#   "Asia/Tokyo", "America/New_York", "Europe/London", "UTC", etc.
# To view all available values:
#   import pytz; print(pytz.all_timezones)
# Reference:
#   IANA database – https://www.iana.org/time-zones
#   Wikipedia – https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
shanghai_tz = pytz.timezone("Asia/Shanghai")

data = [
    {
        "id": i + 1,
        "tsz": shanghai_tz.localize(
            datetime.datetime(2025, 1, 1, 0, 0, 0) + datetime.timedelta(days=i)
        ).isoformat(),
        "vec": [float(i) / 10 for i in range(4)],
    }
    for i in range(data_size)
]

client.insert(collection_name, data)
print("Data inserted successfully.")

// java

// nodejs

// go

# restful

الخطوة 3: عمليات التصفية

TIMESTAMPTZ يدعم المقارنات العددية، والحساب الفاصل، واستخراج مكونات الوقت.

قبل أن تتمكن من إجراء عمليات التصفية على حقول TIMESTAMPTZ ، تأكد مما يلي:

• أنك قد أنشأت فهرسًا لكل حقل متجه.

• تم تحميل المجموعة في الذاكرة.

# Create index on vector field
index_params = client.prepare_index_params()
index_params.add_index(
    field_name="vec",
    index_type="AUTOINDEX",
    index_name="vec_index",
    metric_type="COSINE"
)
client.create_index(collection_name, index_params)
print("Index created successfully.")

# Load the collection
client.load_collection(collection_name)
print(f"Collection '{collection_name}' loaded successfully.")

// java

// nodejs

// go

# restful

استعلام مع تصفية الطابع الزمني

استخدم العوامل الحسابية مثل == و != و < و > و <= و >=. للاطلاع على القائمة الكاملة للعوامل الحسابية المتوفرة في Milvus، راجع العوامل الحسابية.

يقوم المثال أدناه بتصفية الكيانات ذات الطوابع الزمنية (tsz) التي لا تساوي 2025-01-03T00:00:00+08:00:

# Query for entities where tsz is not equal to '2025-01-03T00:00:00+08:00'
expr = "tsz != ISO '2025-01-03T00:00:00+08:00'"

results = client.query(
    collection_name=collection_name,
    filter=expr,
    output_fields=["id", "tsz"],
    limit=10
)

print("Query result: ", results)

# Expected output:
# Query result:  data: ["{'id': 1, 'tsz': '2024-12-31T16:00:00Z'}", "{'id': 2, 'tsz': '2025-01-01T16:00:00Z'}", "{'id': 4, 'tsz': '2025-01-03T16:00:00Z'}", "{'id': 5, 'tsz': '2025-01-04T16:00:00Z'}", "{'id': 6, 'tsz': '2025-01-05T16:00:00Z'}", "{'id': 7, 'tsz': '2025-01-06T16:00:00Z'}", "{'id': 8, 'tsz': '2025-01-07T16:00:00Z'}", "{'id': 9, 'tsz': '2025-01-08T16:00:00Z'}", "{'id': 10, 'tsz': '2025-01-09T16:00:00Z'}", "{'id': 11, 'tsz': '2025-01-10T16:00:00Z'}"]

// java

// nodejs

// go

# restful

في المثال أعلاه،

• tsz هو اسم الحقل TIMESTAMPTZ المُعرَّف في المخطط.

• ISO '2025-01-03T00:00:00+08:00' هو قيمة ثابتة للطابع الزمني بتنسيق ISO 8601 ، بما في ذلك فارق التوقيت الخاص بالمنطقة الزمنية.

• != يقارن قيمة الحقل بتلك القيمة الثابتة. تشمل العوامل الأخرى المدعومة: == و < و <= و > و >=.

عمليات الفاصل الزمني

يمكنك إجراء عمليات حسابية على الحقول TIMESTAMPTZ باستخدام قيم INTERVAL بتنسيق المدة ISO 8601. يتيح لك ذلك إضافة أو طرح فترات زمنية، مثل الأيام أو الساعات أو الدقائق، من الطابع الزمني عند تصفية البيانات.

على سبيل المثال، يقوم الاستعلام التالي بتصفية الكيانات التي لا يساوي فيها الطابع الزمني (tsz) مضافًا إليه صفر يوم 2025-01-03T00:00:00+08:00:

expr = "tsz + INTERVAL 'P0D' != ISO '2025-01-03T00:00:00+08:00'"

results = client.query(
    collection_name, 
    filter=expr, 
    output_fields=["id", "tsz"], 
    limit=10
)

print("Query result: ", results)

# Expected output:
# Query result:  data: ["{'id': 1, 'tsz': '2024-12-31T16:00:00Z'}", "{'id': 2, 'tsz': '2025-01-01T16:00:00Z'}", "{'id': 4, 'tsz': '2025-01-03T16:00:00Z'}", "{'id': 5, 'tsz': '2025-01-04T16:00:00Z'}", "{'id': 6, 'tsz': '2025-01-05T16:00:00Z'}", "{'id': 7, 'tsz': '2025-01-06T16:00:00Z'}", "{'id': 8, 'tsz': '2025-01-07T16:00:00Z'}", "{'id': 9, 'tsz': '2025-01-08T16:00:00Z'}", "{'id': 10, 'tsz': '2025-01-09T16:00:00Z'}", "{'id': 11, 'tsz': '2025-01-10T16:00:00Z'}"]

// java

// nodejs

// go

# restful

البحث باستخدام تصفية الطابع الزمني

يمكنك الجمع بين تصفية « TIMESTAMPTZ » والبحث عن التشابه بين المتجهات لتضييق نطاق النتائج حسب كل من الوقت والتشابه.

# Define a time-based filter expression
filter = "tsz > ISO '2025-01-05T00:00:00+08:00'"

res = client.search(
    collection_name=collection_name,             # Collection name
    data=[[0.1, 0.2, 0.3, 0.4]],                  # Query vector (must match collection's vector dim)
    limit=5,                                      # Max. number of results to return
    filter=filter,                                # Filter expression using TIMESTAMPTZ
    output_fields=["id", "tsz"],  # Fields to include in the search results
)

print("Search result: ", res)

# Expected output:
# Search result:  data: [[{'id': 10, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-09T16:00:00Z', 'id': 10}}, {'id': 9, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-08T16:00:00Z', 'id': 9}}, {'id': 8, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-07T16:00:00Z', 'id': 8}}, {'id': 7, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-06T16:00:00Z', 'id': 7}}, {'id': 6, 'distance': 0.9759000539779663, 'entity': {'tsz': '2025-01-05T16:00:00Z', 'id': 6}}]]

// java

// nodejs

// go

# restful

الاستخدام المتقدم

للاستخدام المتقدم، يمكنك إدارة المناطق الزمنية على مستويات مختلفة (مثل قاعدة البيانات أو المجموعة أو الاستعلام) أو تسريع الاستعلامات على حقول " TIMESTAMPTZ " باستخدام الفهارس.

إدارة المناطق الزمنية على مستويات مختلفة

يمكنك التحكم في المنطقة الزمنية لحقول TIMESTAMPTZ على مستوى قاعدة البيانات أو المجموعة أو الاستعلام/البحث.

للحصول على إرشادات تفصيلية وأمثلة على الأكواد، راجع الصفحات المخصصة:

• تعديل المجموعة

• قاعدة البيانات

• الاستعلام

• البحث المتجهي الأساسي

• البحث الهجين متعدد المتجهات

تسريع الاستعلامات

بشكل افتراضي، ستقوم الاستعلامات على حقول " TIMESTAMPTZ " التي لا تحتوي على فهرس بإجراء مسح كامل لجميع الصفوف، مما قد يؤدي إلى بطء الأداء عند التعامل مع مجموعات البيانات الكبيرة. لتسريع استعلامات الطابع الزمني، قم بإنشاء فهرس " STL_SORT " في حقل " TIMESTAMPTZ " الخاص بك.

للحصول على التفاصيل، راجع STL_SORT.