نمای کلی نمایه

این بخش نمایه‌سازی را برای نسخه Firestore Enterprise شرح می‌دهد. نسخه Firestore Enterprise به‌طور پیش‌فرض هیچ نمایه‌ای ایجاد نمی‌کند. برای کاهش هزینه‌ها و بهبود عملکرد پایگاه داده، برای پُرکاربردترین پُرسمان‌هایتان نمایه ایجاد کنید.

نمایه‌ها تأثیر زیادی بر عملکرد پایگاه داده دارند. اگر نمایه‌ای برای پُرسمان وجود داشته باشد، پایگاه داده می‌تواند با کاهش مقدار داده‌هایی که باید اسکن شوند و کاهش کار لازم برای مرتب‌سازی نتایج، نتایج را به‌طور مؤثر برگرداند. بااین‌حال، ورودی‌های نمایه هزینه‌های ذخیره‌سازی و حجم کار انجام‌شده درطول عملیات نوشتن در فیلدهای نمایه‌شده را افزایش می‌دهد.

تعریف و ساختار نمایه

نمایه شامل موارد زیر است:

• شناسه مجموعه
• فهرستی از فیلدها در مجموعه ارائه‌شده
• حالت نمایه، صعودی، نزولی، یا آرایه-شامل، برای هر فیلد

نمایه همچنین می‌تواند گزینه‌های پراکنده یا یکتا را فعال کند.

ترتیب نمایه

ترتیب و جهت مرتب‌سازی هر فیلد به‌طور منحصربه‌فرد نمایه را تعریف می‌کند. برای مثال، شاخص‌های زیر دو شاخص متمایز هستند و قابل‌تعویض نیستند:

هنگام ایجاد نمایه برای پشتیبانی از پُرسمان، فیلدها را با همان ترتیبی که در پُرسمان شما وجود دارد اضافه کنید.

تراکم نمایه

به‌طور پیش‌فرض، ورودی‌های نمایه داده‌های همه اسناد موجود در مجموعه را ذخیره می‌کنند. این به‌عنوان نمایه غیرپراکنده شناخته می‌شود. یک ورودی نمایه برای یک سند اضافه خواهد شد، صرف‌نظر از اینکه سند حاوی هریک از فیلدهای مشخص‌شده در نمایه باشد یا نه. هنگام تولید ورودی‌های نمایه، فیلدهای غیرموجود به‌عنوان فیلدهای دارای مقدار NULL درنظر گرفته می‌شوند. برای تغییر این رفتار، می‌توانید نمایه را به‌عنوان نمایه پراکنده تعریف کنید.

شاخص‌های پراکنده

نمایه پراکنده فقط اسنادی را در مجموعه نمایه می‌کند که حاوی مقداری (ازجمله null) برای حداقل یکی از فیلدهای نمایه‌شده باشند. نمایه پراکنده هزینه‌های ذخیره‌سازی را کاهش می‌دهد و می‌تواند عملکرد را بهبود بخشد.

نمایه‌های حاوی آرایه

برای بهینه‌سازی عملکرد پُرسمان هنگام پُرسمان کردن فیلد آرایه بااستفاده از array-contains یا array-contains-any، می‌توانید فیلد را در حالت array-contains نمایه‌گذاری کنید. نمایه می‌تواند حداکثر یک فیلد در حالت array-contains داشته باشد.

با نمایه‌سازی فیلد آرایه در حالت array-contains، موتور پُرسمان می‌تواند به‌سرعت اسناد حاوی مقادیر آرایه خاص را پیدا کند. بدون نمایه، پرس‌وجوها مقادیر آرایه را با انجام اسکن کامل مجموعه بررسی می‌کنند، که با افزایش اندازه مجموعه، تأخیر پرس‌وجو و هزینه‌های خواندن را افزایش می‌دهد.

برای نمایه‌سازی فیلد آرایه، فیلد باید شرایط زیر را داشته باشد:

• الزام آرایه غیرخالی: ورودی نمایه فقط درصورتی ایجاد می‌شود که فیلد آرایه در سند وجود داشته باشد و آرایه غیرخالی باشد. اسناد دارای فیلدهای آرایه خالی، غیرآرایه‌ای، یا فاقد فیلد آرایه نمایه‌سازی نمی‌شوند.

چگونه تراکم با نمایه‌های آرایه-شامل مرتبط است

برای نمایه‌هایی که شامل فیلد array-contains هستند، قوانین تراکم نمایه فقط برای فیلدهای نمایه‌شده مرتب‌شده اعمال می‌شود. اگر شرط آرایه غیرخالی برآورده شود، قوانین تراکم برای فیلدهای نمایه‌شده مرتب‌شده باقی‌مانده در نمایه اعمال می‌شود:

• نمایه غیرپراکنده (DENSE): ورودی نمایه برای سند تولید می‌شود. هر فیلد نمایه‌شده مرتب‌شده‌ای که در نمایه وجود نداشته باشد، به‌صورت null در ورودی نمایه ذخیره می‌شود.
• نمایه پراکنده (SPARSE): ورودی نمایه فقط درصورتی تولید می‌شود که حداقل یکی از فیلدهای نمایه‌شده مرتب‌شده در سند وجود داشته باشد.

مثال: تولید ورودی نمایه

نمایه users (tags[*], status ASC) را درنظر بگیرید:

نمونه پُرسمان

// Query for users where 'tags' contains 'news' and 'status' is 'active'
const query = db.collection("users")
  .where("tags", "array-contains", "news")
  .where("status", "==", "active");

// Documents returned by the query:
// [
//   {
//     "id": "alice",
//     "tags": ["news", "tech"],
//     "status": "active"
//   }
// ]

شاخص‌های یکتا

گزینه نمایه یکتا را تنظیم کنید تا مقادیر یکتا برای فیلدهای نمایه‌شده اعمال شود. برای نمایه‌هایی که روی چند فیلد هستند، هر ترکیب از مقادیر باید در سراسر نمایه یکتا باشد. پایگاه داده هرگونه عملیات به‌روزرسانی و درج را که تلاش می‌کند ورودی‌های نمایه با مقادیر تکراری ایجاد کند رد می‌کند. اگر داده‌های فیلدهای نمایه‌شده حاوی مقادیر تکراری باشد و شما تلاش کنید یک نمایه یکتا ایجاد کنید، ساخت نمایه با یک پیام خطا در جزئیات عملیات ناموفق خواهد بود.

فیلدهای غایب در نمایه یکتا

اگر سندی را با فیلدهای مفقود برای نمایه یکتا درج کنید، نمایه مقادیر null را برای فیلدهای مفقود تنظیم می‌کند. ورودی نمایه حاصل باید یکتا باشد، درغیراین‌صورت عملیات ناموفق خواهد بود.

برای مثال، با این نمایه:

اگر سند {"abbreviation": "LA"} را به مجموعه اضافه کنید، نمایه منحصربه‌فرد ورودی‌ای ایجاد می‌کند که در آن name روی null تنظیم شده است. اگر سپس سعی کنید سند {"abbreviation": "NYC"} را اضافه کنید، عملیات ناموفق خواهد بود زیرا ورودی حاصل برای نمایه منحصربه‌فرد یکسان است.

همین رفتار برای نمایه‌های یکتا با چند فیلد اعمال می‌شود. هنگام ایجاد یا به‌روزرسانی سند، فیلدهای نمایه‌شده‌ای که وجود ندارند روی null تنظیم می‌شوند و ورودی نمایه حاصل باید در نمایه منحصربه‌فرد باشد.

نمایه‌های یکتا در مقادیر آرایه

نمایه array-contains منحصربه‌فرد اسناد دارای عناصر آرایه هم‌پوشان را ممنوع می‌کند.

این نوع نمایه الزام نمی‌کند که آرایه دارای مقادیر منحصربه‌فرد در یک سند باشد.

برای مثال، با نمایه یکتا در فیلدی به‌نام tags:

سند زیر، doc1، برای درج معتبر است:

{
  "tags": [ "news", "tech", "news", "music" ]
}

نمایه مقادیر تکراری ("news") را در همان آرایه یک سند واحد مجاز می‌کند.

اگر تلاش کنید سند دومی، doc2، با عنصر تکراری درج کنید، عملیات ناموفق خواهد بود:

{
  "tags": [ "sports", "music" ]
}

عملیات ناموفق است زیرا "music" ازقبل در آرایه doc1 وجود دارد و در نمایه نگاشت شده است.

اگر لازم است مطمئن شوید که عناصر درون یک آرایه در یک سند واحد یکتا هستند، این کار را در منطق برنامه‌تان انجام دهید.

آرایه‌های خالی، فیلدهای ناموجود، و مقادیر تهی

معمولاً فیلدهای مفقود در نمایه یکتا به‌عنوان null درنظر گرفته می‌شوند و باید در سراسر اسناد یکتا باشند (به فیلدهای غایب در نمایه یکتا مراجعه کنید). اما برای نمایه‌های یکتا در فیلدهای آرایه:

• آرایه‌های خالی، فیلدهای مفقود، و مقادیر null مستقل: اگر فیلد آرایه خالی باشد، کاملاً مفقود باشد، یا مقدار مستقل null داشته باشد (نه داخل آرایه)، هیچ کلید نمایه‌ای برای سند تولید نمی‌شود. بنابراین، چندین سند می‌توانند فیلدهای خالی یا مقادیر null مستقل داشته باشند بدون اینکه خطاهای کلید تکراری را فعال کنند.
• عناصر تهی در آرایه: اگر آرایه حاوی مقدار null به‌عنوان عنصر باشد (برای مثال، ["news", null])، عنصر null نمایه‌سازی می‌شود. هر سند بعدی که حاوی عنصر null در فیلد آرایه نمایه‌شده‌اش باشد با خطای کلید تکراری مواجه خواهد شد.

عیب‌یابی خطاهای ساخت نمایه

ممکن است هنگام مدیریت نمایه‌ها با خطاهای ساخت نمایه مواجه شوید. اگر پایگاه داده با مشکلی در داده‌ها مواجه شود، ممکن است عملیات نمایه‌سازی ناموفق باشد. عملیات نمایه‌سازی ممکن است به دلایل زیر ناموفق باشد:

• به حد نمایه رسیده‌اید. برای مثال، ممکن است عملیات به حداکثر تعداد ورودی‌های نمایه در هر سند رسیده باشد. اگر ایجاد نمایه ناموفق باشد، پیام خطا می‌بینید. اگر به حد نمایه نرسیده‌اید، عملیات نمایه را دوباره امتحان کنید.
• گزینه نمایه منحصربه‌فرد را تنظیم کرده‌اید و داده‌های فیلدهای نمایه‌شده ورودی‌های نمایه تکراری ایجاد می‌کند. برای ادامه، ترکیب‌های تکراری مقادیر را از داده‌ها بردارید.

حالا چه می‌شود

با نحوه ایجاد و مدیریت نمایه‌ها آشنا شوید.