Cloud Firestore'daki dizin türleri

Dizinler, veritabanı performansında önemli bir faktördür. Bir kitaptaki konuları sayfa numaralarıyla eşleyen bir kitap dizini gibi, bir veritabanı dizini de bir veritabanındaki öğeleri veritabanındaki konumları ile eşleştirir. Bir veritabanını sorgularken veritabanı, istediğiniz öğelerin konumlarını hızlıca belirlemek için bir dizin kullanabilir.

Bu sayfada, Cloud Firestore'ün kullandığı iki tür dizin (tek alanlı dizinler ve birleşik dizinler) açıklanmaktadır.

Dizin tanımı ve yapısı

Dizin, belirli bir belgenin alan listesinde tanımlanır ve her alan için karşılık gelen bir dizin modu bulunur.

Dizinler, dizin tanımında adı geçen her alan için bir giriş içerir. Dizin, dizin tabanlı sorguların olası sonuçları olan tüm dokümanları içerir. Bir dokümanın dizine eklenebilmesi için dizinde kullanılan her alan için dizine eklenmiş bir değere sahip olması gerekir. Dizin tanımı, belgede değeri ayarlanmamış bir alanı ifade ediyorsa söz konusu belge dizinde görünmez. Bu durumda, doküman hiçbir zaman dizin tabanlı bir sorgunun sonucu olarak döndürülmez.

Bileşik dizin, alan değerlerine göre, dizin tanımında belirtilen sırada sıralanır.

Her sorgunun arkasında bir dizin

Bir sorgu için dizin yoksa çoğu veritabanı, içeriklerini öğe bazında tarar. Bu, veritabanı büyüdükçe daha da yavaş bir işlem olan yavaş bir süreçtir. Cloud Firestore, tüm sorgular için dizinleri kullanarak yüksek sorgu performansı sağlar. Sonuç olarak, sorgu performansı veritabanındaki öğe sayısına değil, sonuç kümesinin boyutuna bağlıdır.

Daha az dizin yönetimi, daha fazla uygulama geliştirme

Cloud Firestore, dizin yönetimi için harcamanız gereken süreyi azaltan özellikler içerir. En temel sorgular için gereken dizinler sizin için otomatik olarak oluşturulur. Cloud Firestore, uygulamanızı kullanırken ve test ederken uygulamanızın ihtiyaç duyduğu ek dizinleri belirlemenize ve oluşturmanıza yardımcı olur.

Dizin türleri

Cloud Firestore iki tür dizin kullanır: tek alanlı ve birleşik. Tek alanlı ve birleşik dizinler, dizine eklenen alan sayısı dışında, bunları yönetme şekliniz açısından da farklılık gösterir.

Tek alanlı dizinler

Tek alanlı dizin, belirli bir alan içeren bir koleksiyondaki tüm dokümanların sıralı eşlemesini depolar. Tek alanlı dizindeki her giriş, bir belgenin belirli bir alan için değerini ve veritabanındaki konumunu kaydeder. Cloud Firestore, birçok temel sorguyu gerçekleştirmek için bu dizinleri kullanır. Tek alan dizinlerini, veritabanınızın otomatik dizine ekleme ayarlarını ve dizin muafiyetlerini yapılandırarak yönetirsiniz.

Otomatik dizine ekleme

Varsayılan olarak Cloud Firestore, bir belgedeki her alan ve haritadaki her alt alan için tek alan dizinlerini otomatik olarak korur. Cloud Firestore tek alanlı dizinler için aşağıdaki varsayılan ayarları kullanır:

• Cloud Firestore, dizi ve harita olmayan her alan için biri artan modda, diğeri azalan modda olmak üzere iki koleksiyon kapsamlı tek alan dizini tanımlar.

• Cloud Firestore her harita alanı için aşağıdakileri oluşturur:

  • Dizi olmayan, harita dışı her alt alan için bir koleksiyon kapsamlı artan dizin.
  • Her dizi ve harita dışı alt alan için bir koleksiyon kapsamlı azalan dizin.
  • Her dizi alt alanı için bir koleksiyon kapsamlı dizi-içerdiği dizini.
  • Cloud Firestore, her harita alt alanını yinelemeli olarak dizine ekler.

• Cloud Firestore, bir belgedeki her dizi alanı için koleksiyon kapsamlı bir dizi-içerdiği dizini oluşturur ve korur.

• Koleksiyon grubu kapsamına sahip tek alan dizinleri varsayılan olarak korunmaz.

Tek alanlı dizin muafiyetleri

Tek alan dizini muafiyeti oluşturarak bir alanı otomatik dizine ekleme ayarlarınızdan muaf tutabilirsiniz. Dizine ekleme muafiyeti, veritabanı genelindeki otomatik dizin ayarlarını geçersiz kılar. Muafiyet, otomatik dizine ekleme ayarlarınızın otomatik dizine eklemenin başka şekilde etkinleştireceği tek alanlı bir dizini devre dışı bırakacağı veya devre dışı bırakacağı tek alanlı bir dizini etkinleştirebilir. Muafiyetlerin yararlı olabileceği durumlar için dizine eklemeyle ilgili en iyi uygulamalara göz atın.

Bir koleksiyon grubundaki tüm alanlara koleksiyon düzeyinde dizin muafiyetleri eklemek için * alan yolu değerini kullanın. Örneğin, comments koleksiyon grubu için alan yolunu comments koleksiyon grubundaki tüm alanlarla eşleşecek şekilde * olarak ayarlayın ve koleksiyon grubu altındaki tüm alanların dizine eklenmesini devre dışı bırakın. Ardından, yalnızca sorgularınız için gerekli alanları dizine eklemek üzere muafiyetler ekleyebilirsiniz. Dizine eklenen alanların sayısını azaltmak depolama alanı maliyetlerini düşürür ve yazma performansını artırabilir.

Bir harita alanı için tek alan dizin muafiyeti oluşturursanız haritanın alt alanları bu ayarları devralır. Ancak belirli alt alanlar için tek alan dizine ekleme muafiyeti tanımlayabilirsiniz. Bir alt alan için muafiyeti silerseniz alt alan, varsa üst alanının muafiyet ayarlarını veya üst muafiyeti yoksa veritabanı genelindeki ayarları devralır.

Tek alan içeren dizin muafiyetleri oluşturmak ve yönetmek için Dizinleri yönetme başlıklı makaleyi inceleyin.

Birleşik dizinler

Bileşik dizin, dizine eklenecek alanların sıralı listesine göre bir koleksiyondaki tüm dokümanların sıralı eşlemesini depolar.

Cloud Firestore, tek alanlı dizinler tarafından desteklenmeyen sorguları desteklemek için birleşik dizinler kullanır.

Cloud Firestore, olası alan kombinasyonlarının çok sayıda olması nedeniyle tek alan dizinlerinde olduğu gibi bileşik dizinleri otomatik olarak oluşturmaz. Bunun yerine Cloud Firestore, uygulamanızı oluştururken gerekli karma dizinleri tanımlamanıza ve oluşturmanıza yardımcı olur.

Bir dizin tarafından desteklenmeyen bir sorgu denediğinizde Cloud Firestore, eksik dizini oluşturmak için izleyebileceğiniz bir bağlantı içeren bir hata mesajı döndürür.

Karma dizinleri konsolu veya Firebase CLI'yi kullanarak manuel olarak da tanımlayıp yönetebilirsiniz. Karma dizin oluşturma ve yönetme hakkında daha fazla bilgi için Dizinleri yönetme başlıklı makaleyi inceleyin.

Dizin modları ve sorgu kapsamları

Tek alan ve bileşik dizinleri farklı şekilde yapılandırırsınız ancak her ikisi için de dizinlerinizin dizine ekleme modlarını ve sorgu kapsamlarını yapılandırmanız gerekir.

Dizin modları

Bir dizin tanımlarken her dizine eklenen alan için bir dizin modu seçersiniz. Her alanın dizin modu, o alanda belirli sorgu deyimlerini destekler. Aşağıdaki dizin modları arasından seçim yapabilirsiniz:

Sorgu kapsamları

Her dizin, bir koleksiyon veya koleksiyon grubu kapsamına alınır. Buna dizindeki sorgu kapsamı denir:

Koleksiyon kapsamı

Cloud Firestore, varsayılan olarak koleksiyon kapsamına sahip dizinler oluşturur. Bu dizinler, tek bir koleksiyondan sonuç döndüren sorguları destekler.

Koleksiyon grubu kapsamı

Koleksiyon grubu, aynı koleksiyon kimliğine sahip tüm koleksiyonları içerir. Bir koleksiyon grubundan filtrelenmiş veya sıralanmış sonuçlar döndüren bir koleksiyon grubu sorgusu çalıştırmak için koleksiyon grubu kapsamına sahip karşılık gelen bir dizin oluşturmanız gerekir.

Varsayılan sıralama ve __name__ alanı

Dizinler, belgeleri her alan için belirtilen dizin modlarına (artan veya azalan) göre sıralamanın yanı sıra her belgenin __name__ alanına göre de son bir sıralama uygular. __name__ alanına doküman yolunun tamamı ayarlanır. Bu, sonuç kümesinde aynı alan değerlerine sahip dokümanların doküman yoluna göre sıralandığı anlamına gelir.

Varsayılan olarak __name__ alanı, dizin tanımındaki son sıralanmış alanla aynı yönde sıralanır. Örneğin:

Sonuçları varsayılan olmayan __name__ yönüne göre sıralamak için bu dizini oluşturmanız gerekir.

Dizin özellikleri

Sorgunun en verimli şekilde yürütülmesine olanak tanıyan bir dizin, aşağıdaki özellikler tarafından tanımlanır:

• Eşitlik filtrelerinde kullanılan alanlar
• Sıralama düzenlerinde kullanılan alanlar
• Aralık ve eşitsizlik filtrelerinde kullanılan alanlar (sıralama ölçütlerine dahil edilmemiş olanlar)
• Toplamalarda kullanılan alanlar (sıralama siparişleri ile aralık ve eşitsizlik filtrelerine halihazırda dahil olmayanlar)

Cloud Firestore, sorguların sonuçlarını aşağıdaki gibi hesaplar:

1. Sorgunun koleksiyonuna, filtre özelliklerine, filtre operatörlerine ve sıralama düzenlerine karşılık gelen dizini tanımlar.
2. Taramanın başladığı dizin konumunu tanımlar. Başlangıç konumuna sorgunun eşitlik filtreleri eklenir ve ilk orderBy alanındaki aralık ve eşitsizlik filtreleriyle sonlandırılır.
3. Tarama işlemi aşağıdakilerden birini yapana kadar dizini taramaya başlar ve tüm filtreleri karşılayan her belgeyi döndürür:
   • Filtre koşullarını karşılamayan bir belgeyle karşılaşır ve sonraki belgelerin hiçbir zaman filtre koşullarını tam olarak karşılamayacağını onaylar.
   • Dizin sonuna ulaşılır.
   • Sorgu tarafından istenen maksimum sonuç sayısını toplar.

Dizine ekleme örneği

Cloud Firestore, sizin için tek alan içeren dizinleri otomatik olarak oluşturarak uygulamanızın en temel veritabanı sorgularını hızlı bir şekilde desteklemesini sağlar. Tek alan dizini, alan değerlerine ve <, <=, ==, >=, > ve in karşılaştırıcılarına göre basit sorgular gerçekleştirmenize olanak tanır. Dizi alanları için array-contains ve array-contains-any sorguları gerçekleştirmenize olanak tanır.

Bunu açıklamak için aşağıdaki örnekleri dizin oluşturma açısından inceleyin. Aşağıdaki snippet, cities koleksiyonunda birkaç city dokümanı oluşturur ve her doküman için name, state, country, capital, population ve tags alanlarını ayarlar:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000,
    regions: ["west_coast", "norcal"] });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000,
    regions: ["west_coast", "socal"] });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000,
    regions: ["east_coast"] });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000,
    regions: ["kanto", "honshu"] });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000,
    regions: ["jingjinji", "hebei"] });
test.firestore.js

Varsayılan otomatik dizine ekleme ayarları varsayarak Cloud Firestore, dizi olmayan her alan için bir artan tek alanlı dizin, dizi olmayan her alan için bir azalan tek alanlı dizin ve dizi alanı için bir dizi içeren tek alanlı dizin günceller. Aşağıdaki tabloda yer alan her satır, tek alanlı dizindeki bir girişi temsil eder:

Tek alanlı dizinler tarafından desteklenen sorgular

Otomatik olarak oluşturulan bu tek alanlı dizinleri kullanarak aşağıdakiler gibi basit sorgular çalıştırabilirsiniz:

const stateQuery = citiesRef.where("state", "==", "CA");
const populationQuery = citiesRef.where("population", "<", 100000);
const nameQuery = citiesRef.where("name", ">=", "San Francisco");
test.firestore.js

in ve birleşik eşitlik (==) sorguları da oluşturabilirsiniz:

citiesRef.where('country', 'in', ["USA", "Japan", "China"])

// Compound equality queries
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("country", "==", "USA")
         .where("capital", "==", false)
         .where("state", "==", "CA")
         .where("population", "==", 860000)

Aralık karşılaştırması (<, <=, > veya >=) kullanan bir karma sorgu çalıştırmanız veya farklı bir alana göre sıralamanız gerekiyorsa söz konusu sorgu için bir karma dizin oluşturmanız gerekir.

array-contains dizini, regions dizi alanını sorgulamanıza olanak tanır:

citiesRef.where("regions", "array-contains", "west_coast")
// array-contains-any and array-contains use the same indexes
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])

Bileşik dizinler tarafından desteklenen sorgular

Cloud Firestore, tek alanlı dizinler tarafından desteklenmeyen bileşik sorguları desteklemek için bileşik dizinler kullanır. Örneğin, aşağıdaki sorgular için birleşik bir dizin gerekir:

citiesRef.where("country", "==", "USA").orderBy("population", "asc")
citiesRef.where("country", "==", "USA").where("population", "<", 3800000)
citiesRef.where("country", "==", "USA").where("population", ">", 690000)
// in and == clauses use the same index
citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)

Bu sorgular için aşağıdaki birleşik dizin gerekir. Sorgu, country alanı için eşitlik (== veya in) kullandığından bu alan için artan veya azalan dizin modunu kullanabilirsiniz. Eşitsizlik yan tümceleri varsayılan olarak eşitsizlik yan tümcesindeki alana göre artan bir sıralama düzeni uygular.

Aynı sorguları azalan bir sıralama düzeniyle çalıştırmak için population için azalan yönde ek bir birleşik dizin oluşturmanız gerekir:

citiesRef.where("country", "==", "USA").orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", "<", 3800000)
         .orderBy("population", "desc")

citiesRef.where("country", "==", "USA")
         .where("population", ">", 690000)
         .orderBy("population", "desc")

citiesRef.where("country", "in", ["USA", "Japan", "China"])
         .where("population", ">", 690000)
         .orderBy("population", "desc")

Dizin birleştirme nedeniyle performans kaybı yaşamamak için bir array-contains veya array-contains-any sorgusunu ek yan tümcelerle birleştirmek üzere karma bir dizin oluşturmanızı öneririz:

citiesRef.where("regions", "array-contains", "east_coast")
         .where("capital", "==", true)

// array-contains-any and array-contains use the same index
citiesRef.where("regions", "array-contains-any", ["west_coast", "east_coast"])
         .where("capital", "==", true)

Koleksiyon grubu dizinleri tarafından desteklenen sorgular

Koleksiyon grubu kapsamlı bir dizini göstermek için city dokümanlarından bazılarına landmarks alt koleksiyonu ekleyin:

var citiesRef = db.collection("cities");

citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Bridge",
    category : "bridge" });
citiesRef.doc("SF").collection("landmarks").doc().set({
    name: "Golden Gate Park",
    category : "park" });

citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Gallery of Art",
    category : "museum" });
citiesRef.doc("DC").collection("landmarks").doc().set({
    name: "National Mall",
    category : "park" });

Koleksiyon kapsamlı aşağıdaki tek alanlı dizini kullanarak category alanına göre tek bir şehrin landmarks koleksiyonunu sorgulayabilirsiniz:

citiesRef.doc("SF").collection("landmarks").where("category", "==", "park")
citiesRef.doc("SF").collection("landmarks").where("category", "in", ["park", "museum"])

Örneğin, tüm şehirlerdeki önemli yerleri sorgulamak istiyorsanız bu sorguyu tüm landmarkskoleksiyonlardan oluşan koleksiyon grubunda çalıştırırsınız. Ayrıca, koleksiyon grubu kapsamına sahip bir landmarks tek alan dizini de etkinleştirmeniz gerekir:

Bu dizin etkinleştirildiğinde landmarks koleksiyon grubunu sorgulayabilirsiniz:

var landmarksGroupRef = db.collectionGroup("landmarks");

landmarksGroupRef.where("category", "==", "park")
landmarksGroupRef.where("category", "in", ["park", "museum"])

Filtrelenmiş veya sıralanmış sonuçlar döndüren bir koleksiyon grubu sorgusu çalıştırmak için koleksiyon grubu kapsamına sahip ilgili bir tek alan veya birleşik dizin etkinleştirmeniz gerekir. Sonuçları filtrelemeyen veya sıralamayan koleksiyon grubu sorguları için ise ek dizin tanımı gerekmez.

Örneğin, ek bir dizin etkinleştirmeden aşağıdaki koleksiyon grubu sorgusunu çalıştırabilirsiniz:

db.collectionGroup("landmarks").get()

Dizin girişleri

Bir belgenin dizin girişlerinin sayısı, projenizin yapılandırılmış dizinleri ve belge yapısı tarafından belirlenir. Dizin girişleri, dizin girişi sayısı sınırına dahil edilir.

Aşağıdaki örnekte bir belgenin dizin girişleri gösterilmektedir.

Doküman

/cities/SF

city_name : "San Francisco"
temperatures : {summer: 67, winter: 55}
neighborhoods : ["Mission", "Downtown", "Marina"]

Tek alanlı dizinler

• city_name ASC
• city_name DESC
• temperatures.summer ASC
• temperatures.summer DESC
• sıcaklıklar.winter ASC
• sıcaklıklar.winter DESC
• neighborhoods Dizisi İçerir (ASC ve DESC)

Birleşik dizinler

• city_name ASC, neighborhoods ARRAY
• city_name DESC, neighborhoods ARRAY

Dizin girişleri

Bu dizine ekleme yapılandırması, doküman için aşağıdaki dizin girişleriyle sonuçlanır:

Dizinler ve fiyatlandırma

Dizinler, uygulamanızın depolama maliyetlerine katkıda bulunur. Dizinler için depolama alanının nasıl hesaplanacağı hakkında daha fazla bilgi edinmek için Dizin girişi boyutu bölümüne bakın.

Dizin birleştirme özelliğini kullanma

Cloud Firestore her sorgu için bir dizin kullansa da her sorgu için bir dizin gerekmez. Birden fazla eşitlik (==) yan tümcesi ve isteğe bağlı olarak bir orderBy yan tümcesi içeren sorgular için Cloud Firestore, mevcut dizinleri yeniden kullanabilir. Cloud Firestore, daha büyük eşitlik sorguları için gereken birleşik dizinleri oluşturmak üzere basit eşitlik filtrelerinin dizinlerini birleştirebilir.

Dizin birleştirme işlemini kullanabileceğiniz durumları belirleyerek dizine ekleme maliyetlerini azaltabilirsiniz. Örneğin, bir restoran puanlama uygulamasının restaurants koleksiyonunda:

• collections_bookmark restoran

  • class hamburger

    name : "Burger Thyme"
category : "burgers"
city : "San Francisco"
editors_pick : true
star_rating : 4
    

Bu uygulama aşağıdaki gibi sorgular kullanır. Uygulama, her zaman star_rating artan düzenine göre sıralarken category, city ve editors_pick için eşitlik yan tümcelerinin kombinasyonlarını kullanır:

db.collection("restaurants").where("category", "==", "burgers")
                            .orderBy("star_rating")

db.collection("restaurants").where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==", "San Francisco")
                            .orderBy("star_rating")

db.collection("restaurants").where("category", "==", "burgers")
                            .where("city", "==" "San Francisco")
                            .where("editors_pick", "==", true )
                            .orderBy("star_rating")

Her sorgu için bir dizin oluşturabilirsiniz:

Daha iyi bir çözüm olarak, Cloud Firestore'ın eşitlik koşulları için dizinleri birleştirme özelliğinden yararlanarak dizin sayısını azaltabilirsiniz:

Bu dizin grubu yalnızca daha küçük değil, aynı zamanda ek bir sorguyu da destekler:

db.collection("restaurants").where("editors_pick", "==", true)
                            .orderBy("star_rating")

Dizine ekleme sınırları

Aşağıdaki sınırlar dizinler için geçerlidir. Kotalar ve sınırlar hakkında daha fazla bilgi için Kotalar ve Sınırlar bölümüne bakın.

Dizine eklemeyle ilgili en iyi uygulamalar

Çoğu uygulamada, dizine ekleme işlemlerinizi yönetmek için otomatik dizine ekleme özelliğini ve hata mesajı bağlantılarını kullanabilirsiniz. Ancak aşağıdaki durumlarda tek alan muafiyeti eklemek isteyebilirsiniz:

Birden fazla alanda aralık ve eşitsizlik operatörleri içeren sorgular kullanıyorsanız Cloud Firestore sorgularının performansını ve maliyetini optimize etmek için göz önünde bulundurmanız gereken dizine eklemeyle ilgili hususlara bakın.

Dizine ekleme sorunları (dizin dağıtımı, INVALID_ARGUMENT hataları) nasıl çözüleceği hakkında daha fazla bilgi için sorun giderme sayfasına bakın.