حقل 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).

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

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

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

الخطوة 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

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

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

يقوم المثال أدناه بتصفية الكيانات ذات الطوابع الزمنية (tsz) التي لا تساوي 2025-01-03T00:00: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: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.