SQL Server 2025 JSON_CONTAINS کشف داده ها در JSON

SQL Server 2025: کشف داده‌ها در JSON با تابع JSON_CONTAINS

SQL Server 2025 با معرفی تابع JSON_CONTAINS، قابلیت‌های مدیریت و کار با داده‌های JSON را بهبود بخشیده است. این تابع قدرتمند، امکان بررسی وجود یک مقدار اسکالر (scalar value)، یک شیء JSON یا یک آرایه JSON را در یک سند JSON مشخص فراهم می‌کند. برخلاف JSON_EXISTS که تنها وجود هر مقداری را در یک مسیر خاص بررسی می‌کند، JSON_CONTAINS به شما اجازه می‌دهد تا با دقت بیشتری به دنبال محتوای خاص بگردید. این مقاله به بررسی جامع JSON_CONTAINS، نحوه استفاده از آن و تفاوت‌های کلیدی‌اش با سایر توابع مرتبط می‌پردازد تا در مدیریت داده‌های JSON در SQL Server 2025 کارایی شما را افزایش دهد.

ساختار تابع JSON_CONTAINS

تابع JSON_CONTAINS به شما این امکان را می‌دهد که بررسی کنید آیا یک مقدار JSON در یک سند JSON اصلی موجود است یا خیر. ساختار کلی آن به شرح زیر است:

JSON_CONTAINS ( json_text , json_path , json_value [ , is_array_check ] )

پارامترها:

• json_text: این پارامتر رشته JSON اصلی است که می‌خواهیم در آن جستجو کنیم.
• json_path: این مسیر JSON است که مشخص می‌کند در کدام بخش از json_text باید به دنبال json_value بگردیم.
• json_value: این مقدار JSON (اسکالر، شیء یا آرایه) است که وجود آن را در json_path بررسی می‌کنیم.
• is_array_check: یک پارامتر اختیاری با مقدار بولی (TRUE/FALSE) است. اگر TRUE باشد، تابع تنها زمانی TRUE برمی‌گرداند که json_value یک آرایه باشد و در json_path یافت شود.

نوع بازگشتی JSON_CONTAINS

این تابع یک مقدار بولی برمی‌گرداند:

• 1: اگر json_value در json_path داخل json_text یافت شود.
• 0: اگر json_value یافت نشود.
• NULL: اگر json_text یا json_path نامعتبر باشد.

مثال‌ها: کاربرد تابع JSON_CONTAINS

در این بخش، با مثال‌های عملی، نحوه استفاده از تابع JSON_CONTAINS را برای سناریوهای مختلف بررسی می‌کنیم. این مثال‌ها به شما کمک می‌کنند تا درک عمیق‌تری از قابلیت‌های این تابع در SQL Server 2025 پیدا کنید.

بررسی وجود مقدار اسکالر

این مثال‌ها نشان می‌دهند که چگونه می‌توان وجود یک مقدار تکی (مانند رشته یا عدد) را در یک سند JSON بررسی کرد.

مثال ۱: بررسی وجود یک رشته (بدون مسیر مشخص)
در این مثال، می‌خواهیم بررسی کنیم که آیا رشته ‘SQL Server’ در کل سند JSON وجود دارد یا خیر.

SELECT JSON_CONTAINS('{"name": "SQL Server", "version": 2025}', '$', 'SQL Server') AS Result;

نتیجه این کوئری 1 خواهد بود، زیرا ‘SQL Server’ در سند JSON یافت می‌شود.

مثال ۲: بررسی وجود یک عدد (بدون مسیر مشخص)
این کوئری بررسی می‌کند که آیا عدد 100 در هر کجای سند JSON موجود است.

SELECT JSON_CONTAINS('{"id": 123, "value": 100, "active": true}', '$', 100) AS Result;

نتیجه 1 خواهد بود، زیرا عدد 100 در سند JSON وجود دارد.

مثال ۳: بررسی وجود یک رشته در مسیر مشخص
در این حالت، به دنبال رشته ‘SQL Server’ در مسیر $.product می‌گردیم.

SELECT JSON_CONTAINS('{"product": "SQL Server", "year": 2025}', '$.product', 'SQL Server') AS Result;

نتیجه 1 است، زیرا ‘SQL Server’ به عنوان مقدار کلید product یافت می‌شود.

مثال ۴: بررسی وجود یک رشته در مسیر مشخص (مورد عدم وجود)
این مثال نشان می‌دهد که وقتی مقدار مورد نظر در مسیر مشخص شده یافت نشود، چه اتفاقی می‌افتد.

SELECT JSON_CONTAINS('{"product": "Azure SQL", "year": 2025}', '$.product', 'SQL Server') AS Result;

نتیجه 0 خواهد بود، زیرا ‘SQL Server’ در مسیر $.product یافت نمی‌شود.

بررسی وجود شیء JSON

این بخش به چگونگی جستجوی اشیاء JSON در یک سند می‌پردازد.

مثال ۵: بررسی وجود یک شیء ساده
در این کوئری، به دنبال یک شیء JSON کامل {“city”: “New York”} در مسیر $.address می‌گردیم.

SELECT JSON_CONTAINS('{"user": {"name": "Alice", "address": {"city": "New York", "zip": "10001"}}}', '$.user.address', '{"city": "New York"}') AS Result;

نتیجه 1 است، زیرا شیء {“city”: “New York”} به عنوان بخشی از شیء address در مسیر $.user.address یافت می‌شود.

مثال ۶: بررسی وجود یک شیء با چندین ویژگی
این مثال نشان می‌دهد که چگونه می‌توان وجود یک شیء با ویژگی‌های متعدد را بررسی کرد.

SELECT JSON_CONTAINS('{"item": {"name": "Laptop", "price": 1200, "currency": "USD"}}', '$.item', '{"name": "Laptop", "price": 1200}') AS Result;

نتیجه 1 است، زیرا شیء {“name”: “Laptop”, “price”: 1200} به عنوان زیرمجموعه‌ای از شیء item در مسیر $.item یافت می‌شود. اگر یکی از ویژگی‌ها (مانند currency) در json_value نباشد ولی در json_text باشد، همچنان 1 برمی‌گرداند به شرطی که json_value به طور کامل در json_text یافت شود.

مثال ۷: بررسی وجود یک شیء تو در تو
این کوئری به دنبال یک شیء تو در تو {“detail”: {“brand”: “Dell”}} در مسیر $.product می‌گردد.

SELECT JSON_CONTAINS('{"product": {"name": "Monitor", "spec": {"detail": {"brand": "Dell", "size": "27"}}}}}', '$.product.spec', '{"detail": {"brand": "Dell"}}') AS Result;

نتیجه 1 است، زیرا شیء تو در تو مورد نظر در مسیر مشخص شده وجود دارد.

بررسی وجود آرایه JSON

این بخش به چگونگی جستجوی آرایه‌های JSON در یک سند می‌پردازد.

مثال ۸: بررسی وجود یک آرایه ساده
این کوئری بررسی می‌کند که آیا آرایه [10, 20] در مسیر $.numbers موجود است.

SELECT JSON_CONTAINS('{"data": {"numbers": [10, 20, 30], "letters": ["a", "b"]}}', '$.data.numbers', '[10, 20]') AS Result;

نتیجه 1 است، زیرا آرایه [10, 20] به عنوان زیرمجموعه‌ای از آرایه numbers در مسیر $.data.numbers یافت می‌شود. ترتیب و تعداد عناصر در json_value مهم است.

مثال ۹: بررسی وجود یک آرایه از اشیاء
در این مثال، به دنبال آرایه‌ای از اشیاء [{“item”: “A”}, {“item”: “B”}] در مسیر $.products می‌گردیم.

SELECT JSON_CONTAINS('{"products": [{"item": "A"}, {"item": "B"}, {"item": "C"}]}', '$.products', '[{"item": "A"}, {"item": "B"}]') AS Result;

نتیجه 1 است، زیرا آرایه اشیاء مورد نظر در مسیر $.products یافت می‌شود.

استفاده از پارامتر is_array_check

این پارامتر اختیاری امکان بررسی دقیق‌تر نوع داده را فراهم می‌کند.

مثال ۱۰: استفاده از is_array_check برای اطمینان از آرایه بودن مقدار
در این مثال، می‌خواهیم بررسی کنیم که آیا مقدار در مسیر $.tags یک آرایه است و شامل ‘SQL Server’ نیز می‌شود.

SELECT JSON_CONTAINS('{"product": "SQL Server 2025", "tags": ["Database", "SQL Server", "Microsoft"]}', '$.tags', '["SQL Server"]', TRUE) AS Result;

نتیجه 1 است. TRUE در پارامتر چهارم تضمین می‌کند که $.tags باید یک آرایه باشد و شامل ‘SQL Server’ باشد.

مثال ۱۱: استفاده از is_array_check با یک شیء (برگشت 0)
در این کوئری، با وجود اینکه ‘SQL Server’ در سند JSON وجود دارد، is_array_check باعث می‌شود که تابع 0 برگرداند، زیرا $.product یک شیء اسکالر است نه یک آرایه.

SELECT JSON_CONTAINS('{"product": "SQL Server", "year": 2025}', '$.product', '"SQL Server"', TRUE) AS Result;

نتیجه 0 خواهد بود، زیرا مقدار در $.product یک رشته است و نه یک آرایه.

تفاوت JSON_CONTAINS با JSON_EXISTS

در حالی که هر دو تابع JSON_CONTAINS و JSON_EXISTS برای بررسی وجود داده‌ها در JSON در SQL Server 2025 استفاده می‌شوند، تفاوت‌های مهمی دارند که آن‌ها را برای سناریوهای مختلف مناسب می‌سازد:

• JSON_EXISTS: تنها بررسی می‌کند که آیا یک مقدار (از هر نوعی) در یک مسیر JSON خاص وجود دارد یا خیر.
• JSON_CONTAINS: با دقت بیشتری عمل می‌کند و بررسی می‌کند که آیا یک مقدار JSON مشخص (اسکالر، شیء یا آرایه) در یک مسیر JSON خاص وجود دارد یا خیر.

برای درک بهتر، به مثال زیر توجه کنید:

DECLARE @json nvarchar(max) = '{"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}';

SELECT
    JSON_EXISTS(@json, '$.users[0].name') AS JsonExistsResult,
    JSON_CONTAINS(@json, '$.users[0].name', '"Alice"') AS JsonContainsResult;

• JsonExistsResult برابر با 1 خواهد بود، زیرا نام در مسیر $.users[0].name وجود دارد.
• JsonContainsResult نیز برابر با 1 خواهد بود، زیرا مقدار ‘”Alice”‘ در مسیر $.users[0].name یافت می‌شود.

حالا فرض کنید می‌خواهیم ببینیم آیا یک شیء خاص در آرایه users وجود دارد:

DECLARE @json2 nvarchar(max) = '{"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}';

SELECT
    JSON_EXISTS(@json2, '$.users[0]') AS JsonExistsResult,
    JSON_CONTAINS(@json2, '$.users[0]', '{"id": 1, "name": "Alice"}') AS JsonContainsResult;

• JsonExistsResult برابر با 1 است، زیرا یک شیء در $.users[0] وجود دارد.
• JsonContainsResult نیز 1 است، زیرا شیء {“id”: 1, “name”: “Alice”} دقیقاً در $.users[0] یافت می‌شود.

JSON_CONTAINS این امکان را فراهم می‌کند که از نظر محتوایی بررسی‌های دقیق‌تری انجام دهید، نه فقط وجود ساختاری.

ملاحظات عملکردی

هنگام کار با JSON_CONTAINS در SQL Server 2025، به ویژه با اسناد JSON بزرگ یا کوئری‌های مکرر، توجه به عملکرد اهمیت دارد.

• اندازه سند JSON: جستجو در اسناد JSON بسیار بزرگ می‌تواند منابع قابل توجهی مصرف کند.
• پیچیدگی json_path: مسیرهای JSON پیچیده ممکن است پردازش بیشتری نیاز داشته باشند.
• استفاده از ایندکس: در حال حاضر، SQL Server ایندکس‌های مستقیمی برای داده‌های JSON داخلی ندارد که بتوانند مستقیماً JSON_CONTAINS را بهبود بخشند. با این حال، می‌توان با استفاده از ستون‌های محاسباتی پایدار (persisted computed columns) و توابع JSON_VALUE یا JSON_QUERY برای استخراج مقادیر یا اشیاء JSON پرکاربرد و سپس ایندکس‌گذاری روی این ستون‌ها، عملکرد را بهبود بخشید.

مثال: ایجاد ستون محاسباتی برای ایندکس‌گذاری:

ALTER TABLE YourTable ADD ProductName AS JSON_VALUE(JsonColumn, '$.product.name') PERSISTED;
CREATE INDEX IX_ProductName ON YourTable(ProductName);

سپس می‌توانید کوئری‌هایی که روی ProductName فیلتر می‌کنند را بهینه‌سازی کنید. با این حال، این روش برای JSON_CONTAINS که به دنبال یک شیء یا آرایه کامل است، به طور مستقیم کارایی کمتری دارد و بیشتر برای مقادیر اسکالر مناسب است.

نتیجه‌گیری

تابع JSON_CONTAINS در SQL Server 2025 ابزاری قدرتمند برای اعتبارسنجی و جستجوی دقیق محتوا در اسناد JSON ارائه می‌دهد. با قابلیت بررسی وجود مقادیر اسکالر، اشیاء و آرایه‌ها، این تابع به توسعه‌دهندگان کمک می‌کند تا منطق پیچیده‌تری را برای مدیریت داده‌های JSON پیاده‌سازی کنند. درک صحیح نحوه استفاده از آن و توجه به تفاوت‌هایش با توابعی مانند JSON_EXISTS، برای نوشتن کوئری‌های کارآمد و بهینه ضروری است. این قابلیت جدید، انعطاف‌پذیری بیشتری را در کار با داده‌های نیمه ساختاریافته در SQL Server 2025 به ارمغان می‌آورد و بهره‌وری شما را در پروژه‌های دیتابیسی افزایش می‌دهد.