Azure Cosmos DB'de dizin oluşturma ilkelerini yönetme

ŞUNLAR IÇIN GEÇERLIDIR: SQL API

Azure Cosmos DB'de veriler, her kapsayıcı için tanımlanan dizin oluşturma ilkelerine göre dizinlenir. Yeni oluşturulan kapsayıcıların varsayılan dizin oluşturma ilkesi tüm dizeler veya sayılar için aralık dizinlerini zorunlu tutar. Bu ilke kendi özel dizin oluşturma ilkenizle geçersiz kılınabilir.

Not

Bu makalede açıklanan dizin oluşturma ilkelerini güncelleştirme yöntemi yalnızca Azure Cosmos DB'nin SQL (Çekirdek) API'sine uygulanır. Azure Cosmos DB API'sinde MongoDB için dizin oluşturma ve Azure Cosmos DB Cassandra API ikincil dizin oluşturma hakkında bilgi edinin.

Dizin oluşturma ilkesi örnekleri

Burada, Azure portal nasıl kullanıma sunulduğuna ilişkin JSON biçiminde gösterilen dizin oluşturma ilkelerine bazı örnekler verilmiştir. Aynı parametreler Azure CLI veya herhangi bir SDK aracılığıyla ayarlanabilir.

Bazı özellik yollarını seçmeli olarak dışlamak için ilkeyi geri çevirme

    {
        "indexingMode": "consistent",
        "includedPaths": [
            {
                "path": "/*"
            }
        ],
        "excludedPaths": [
            {
                "path": "/path/to/single/excluded/property/?"
            },
            {
                "path": "/path/to/root/of/multiple/excluded/properties/*"
            }
        ]
    }

Bu dizin oluşturma ilkesi, , dataTypeve precision değerlerini varsayılan değerlerine el ile ayarlayan kindaşağıdaki ilkeyle eşdeğerdir. Bu özelliklerin açıkça ayarlanması artık gerekli değildir ve bunları dizin oluşturma ilkenizden tamamen atlamalısınız (yukarıdaki örnekte gösterildiği gibi). Bu özellikleri ayarlamaya çalışırsanız, bunlar dizin oluşturma ilkenizden otomatik olarak kaldırılır.

    {
        "indexingMode": "consistent",
        "includedPaths": [
            {
                "path": "/*",
                "indexes": [
                    {
                        "kind": "Range",
                        "dataType": "Number",
                        "precision": -1
                    },
                    {
                        "kind": "Range",
                        "dataType": "String",
                        "precision": -1
                    }
                ]
            }
        ],
        "excludedPaths": [
            {
                "path": "/path/to/single/excluded/property/?"
            },
            {
                "path": "/path/to/root/of/multiple/excluded/properties/*"
            }
        ]
    }

Bazı özellik yollarını seçmeli olarak eklemek için kabul etme ilkesi

    {
        "indexingMode": "consistent",
        "includedPaths": [
            {
                "path": "/path/to/included/property/?"
            },
            {
                "path": "/path/to/root/of/multiple/included/properties/*"
            }
        ],
        "excludedPaths": [
            {
                "path": "/*"
            }
        ]
    }

Bu dizin oluşturma ilkesi, , dataTypeve precision değerlerini varsayılan değerlerine el ile ayarlayan kindaşağıdaki ilkeyle eşdeğerdir. Bu özelliklerin açıkça ayarlanması artık gerekli değildir ve bunları dizin oluşturma ilkenizden tamamen atlamalısınız (yukarıdaki örnekte gösterildiği gibi). Bu özellikleri ayarlamaya çalışırsanız, bunlar dizin oluşturma ilkenizden otomatik olarak kaldırılır.

    {
        "indexingMode": "consistent",
        "includedPaths": [
            {
                "path": "/path/to/included/property/?",
                "indexes": [
                    {
                        "kind": "Range",
                        "dataType": "Number"
                    },
                    {
                        "kind": "Range",
                        "dataType": "String"
                    }
                ]
            },
            {
                "path": "/path/to/root/of/multiple/included/properties/*",
                "indexes": [
                    {
                        "kind": "Range",
                        "dataType": "Number"
                    },
                    {
                        "kind": "Range",
                        "dataType": "String"
                    }
                ]
            }
        ],
        "excludedPaths": [
            {
                "path": "/*"
            }
        ]
    }

Not

Azure Cosmos DB'nin veri modelinize eklenebilen yeni özellikleri proaktif olarak dizine eklemesine izin vermek için bir geri çevirme dizin oluşturma ilkesinin kullanılması genellikle önerilir.

Yalnızca belirli bir özellik yolunda uzamsal dizin kullanma

{
    "indexingMode": "consistent",
    "automatic": true,
    "includedPaths": [
        {
            "path": "/*"
        }
    ],
    "excludedPaths": [
        {
            "path": "/_etag/?"
        }
    ],
    "spatialIndexes": [
        {
            "path": "/path/to/geojson/property/?",
            "types": [
                "Point",
                "Polygon",
                "MultiPolygon",
                "LineString"
            ]
        }
    ]
}

Bileşik dizin oluşturma ilkesi örnekleri

Tek tek özellikler için yolları eklemeye veya dışlamanın yanı sıra, bileşik dizin de belirtebilirsiniz. Birden çok özellik için yan tümcesi olan bir ORDER BY sorgu gerçekleştirmek isterseniz, bu özellikler üzerinde bileşik dizin gerekir. Ayrıca bileşik dizinler, birden çok filtreye veya hem filtreye hem de ORDER BY yan tümcesine sahip sorgular için performans avantajına sahip olur.

Not

Yalnızca bu yoldaki skaler değer dizine eklendiğinden bileşik yolların örtük /? bir değeri vardır. Joker /* karakter bileşik yollarda desteklenmez. Bileşik bir yol belirtmemeniz /?/* gerekir.

için tanımlanan bileşik dizin (name asc, age desc):

    {  
        "automatic":true,
        "indexingMode":"Consistent",
        "includedPaths":[  
            {  
                "path":"/*"
            }
        ],
        "excludedPaths":[],
        "compositeIndexes":[  
            [  
                {  
                    "path":"/name",
                    "order":"ascending"
                },
                {  
                    "path":"/age",
                    "order":"descending"
                }
            ]
        ]
    }

Yukarıdaki ad ve yaş bileşik dizini Sorgu #1 ve Sorgu #2 için gereklidir:

1. Sorgu:

    SELECT *
    FROM c
    ORDER BY c.name ASC, c.age DESC

Sorgu #2:

    SELECT *
    FROM c
    ORDER BY c.name DESC, c.age ASC

Bu bileşik dizin Sorgu #3 ve Sorgu #4'e fayda sağlar ve filtreleri iyileştirir:

Sorgu #3:

SELECT *
FROM c
WHERE c.name = "Tim"
ORDER BY c.name DESC, c.age ASC

Sorgu #4:

SELECT *
FROM c
WHERE c.name = "Tim" AND c.age > 18

için tanımlanan bileşik dizin (ad ASC, yaş ASC) ve (ad ASC, yaş DESC):

Aynı dizin oluşturma ilkesi içinde birden çok farklı bileşik dizin tanımlayabilirsiniz.

    {  
        "automatic":true,
        "indexingMode":"Consistent",
        "includedPaths":[  
            {  
                "path":"/*"
            }
        ],
        "excludedPaths":[],
        "compositeIndexes":[  
            [  
                {  
                    "path":"/name",
                    "order":"ascending"
                },
                {  
                    "path":"/age",
                    "order":"ascending"
                }
            ],
            [  
                {  
                    "path":"/name",
                    "order":"ascending"
                },
                {  
                    "path":"/age",
                    "order":"descending"
                }
            ]
        ]
    }

için tanımlanan bileşik dizin (ad ASC, yaş ASC):

Sırayı belirtmek isteğe bağlıdır. Belirtilmezse, sıra artandır.

{  
        "automatic":true,
        "indexingMode":"Consistent",
        "includedPaths":[  
            {  
                "path":"/*"
            }
        ],
        "excludedPaths":[],
        "compositeIndexes":[  
            [  
                {  
                    "path":"/name",
                },
                {  
                    "path":"/age",
                }
            ]
        ]
}

Tüm özellik yollarını dışlama ama dizin oluşturmayı etkin tutma

Bu ilke, Yaşam Süresi (TTL) özelliğinin etkin olduğu ancak ek dizin gerekmeyen durumlarda kullanılabilir (Azure Cosmos DB'yi saf anahtar-değer deposu olarak kullanmak için).

    {
        "indexingMode": "consistent",
        "includedPaths": [],
        "excludedPaths": [{
            "path": "/*"
        }]
    }

Dizin oluşturma yok

Bu ilke dizin oluşturmayı kapatır. olarak ayarlanırsa indexingModenone, kapsayıcıda bir TTL ayarlayamazsınız.

    {
        "indexingMode": "none"
    }

Dizin oluşturma ilkesi güncelleştiriliyor

Azure Cosmos DB'de dizin oluşturma ilkesi aşağıdaki yöntemlerden herhangi biri kullanılarak güncelleştirilebilir:

  • Azure portal
  • Azure CLI'yi kullanma
  • PowerShell kullanma
  • SDK'lardan birini kullanma

Dizin oluşturma ilkesi güncelleştirmesi dizin dönüştürmeyi tetikler. Bu dönüşümün ilerleme durumu SDK'lardan da izlenebilir.

Not

Dizin oluşturma ilkesi güncelleştirilirken Azure Cosmos DB'ye yazma işlemleri kesintiye uğramaz. Dizin dönüştürmeleri hakkında daha fazla bilgi edinin

Azure portalını kullanma

Azure Cosmos kapsayıcıları, dizin oluşturma ilkelerini Azure portal doğrudan düzenlemenize olanak tanıyan bir JSON belgesi olarak depolar.

  1. Azure Portal’ında oturum açın.

  2. Yeni bir Azure Cosmos hesabı oluşturun veya mevcut bir hesabı seçin.

  3. Veri Gezgini bölmesini açın ve üzerinde çalışmak istediğiniz kapsayıcıyı seçin.

  4. Ölçek & Ayarlar'ne tıklayın.

  5. Dizin oluşturma ilkesi JSON belgesini değiştirme ( aşağıdaki örneklere bakın)

  6. İşiniz bittiğinde Kaydet’e tıklayın.

Manage Indexing using Azure portal

Azure CLI kullanma

Özel dizin oluşturma ilkesiyle kapsayıcı oluşturmak için bkz. CLI kullanarak özel dizin ilkesiyle kapsayıcı oluşturma

PowerShell kullanma

Özel dizin oluşturma ilkesiyle kapsayıcı oluşturmak için bkz. PowerShell kullanarak özel dizin ilkesiyle kapsayıcı oluşturma

.NET SDK’yı kullanma

DocumentCollection.NET SDK v2'den nesnesi, ve öğesini değiştirmenize IndexingMode ve ekleyip kaldırmanıza IncludedPathsExcludedPathsolanak tanıyan bir IndexingPolicy özelliği kullanıma sunar.

// Retrieve the container's details
ResourceResponse<DocumentCollection> containerResponse = await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri("database", "container"));
// Set the indexing mode to consistent
containerResponse.Resource.IndexingPolicy.IndexingMode = IndexingMode.Consistent;
// Add an included path
containerResponse.Resource.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
// Add an excluded path
containerResponse.Resource.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/name/*" });
// Add a spatial index
containerResponse.Resource.IndexingPolicy.SpatialIndexes.Add(new SpatialSpec() { Path = "/locations/*", SpatialTypes = new Collection<SpatialType>() { SpatialType.Point } } );
// Add a composite index
containerResponse.Resource.IndexingPolicy.CompositeIndexes.Add(new Collection<CompositePath> {new CompositePath() { Path = "/name", Order = CompositePathSortOrder.Ascending }, new CompositePath() { Path = "/age", Order = CompositePathSortOrder.Descending }});
// Update container with changes
await client.ReplaceDocumentCollectionAsync(containerResponse.Resource);

Dizin dönüştürme işleminin ilerleme durumunu izlemek için özelliğini trueolarak ayarlayan PopulateQuotaInfo bir RequestOptions nesne geçirin.

// retrieve the container's details
ResourceResponse<DocumentCollection> container = await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri("database", "container"), new RequestOptions { PopulateQuotaInfo = true });
// retrieve the index transformation progress from the result
long indexTransformationProgress = container.IndexTransformationProgress;

Java SDK'sını kullanma

Java SDK'sındanDocumentCollection gelen nesne (kullanımıyla ilgili bu Hızlı Başlangıç'a bakın) kullanıma sunar getIndexingPolicy() ve setIndexingPolicy() yöntemleri. yönlendirdikleri IndexingPolicy nesne, dizin oluşturma modunu değiştirmenize ve dahil edilen ve dışlanan yolları eklemenize veya kaldırmanıza olanak tanır.

// Retrieve the container's details
Observable<ResourceResponse<DocumentCollection>> containerResponse = client.readCollection(String.format("/dbs/%s/colls/%s", "database", "container"), null);
containerResponse.subscribe(result -> {
DocumentCollection container = result.getResource();
IndexingPolicy indexingPolicy = container.getIndexingPolicy();

// Set the indexing mode to consistent
indexingPolicy.setIndexingMode(IndexingMode.Consistent);

// Add an included path

Collection<IncludedPath> includedPaths = new ArrayList<>();
IncludedPath includedPath = new IncludedPath();
includedPath.setPath("/*");
includedPaths.add(includedPath);
indexingPolicy.setIncludedPaths(includedPaths);

// Add an excluded path

Collection<ExcludedPath> excludedPaths = new ArrayList<>();
ExcludedPath excludedPath = new ExcludedPath();
excludedPath.setPath("/name/*");
excludedPaths.add(excludedPath);
indexingPolicy.setExcludedPaths(excludedPaths);

// Add a spatial index

Collection<SpatialSpec> spatialIndexes = new ArrayList<SpatialSpec>();
Collection<SpatialType> collectionOfSpatialTypes = new ArrayList<SpatialType>();

SpatialSpec spec = new SpatialSpec();
spec.setPath("/locations/*");
collectionOfSpatialTypes.add(SpatialType.Point);
spec.setSpatialTypes(collectionOfSpatialTypes);
spatialIndexes.add(spec);

indexingPolicy.setSpatialIndexes(spatialIndexes);

// Add a composite index

Collection<ArrayList<CompositePath>> compositeIndexes = new ArrayList<>();
ArrayList<CompositePath> compositePaths = new ArrayList<>();

CompositePath nameCompositePath = new CompositePath();
nameCompositePath.setPath("/name");
nameCompositePath.setOrder(CompositePathSortOrder.Ascending);

CompositePath ageCompositePath = new CompositePath();
ageCompositePath.setPath("/age");
ageCompositePath.setOrder(CompositePathSortOrder.Descending);

compositePaths.add(ageCompositePath);
compositePaths.add(nameCompositePath);

compositeIndexes.add(compositePaths);
indexingPolicy.setCompositeIndexes(compositeIndexes);

// Update the container with changes

 client.replaceCollection(container, null);
});

Kapsayıcıdaki dizin dönüştürme ilerleme durumunu izlemek için kota bilgilerinin doldurulma isteğinde bulunan bir RequestOptions nesneyi geçirin ve ardından yanıt üst bilgisinden x-ms-documentdb-collection-index-transformation-progress değeri alın.

// set the RequestOptions object
RequestOptions requestOptions = new RequestOptions();
requestOptions.setPopulateQuotaInfo(true);
// retrieve the container's details
Observable<ResourceResponse<DocumentCollection>> containerResponse = client.readCollection(String.format("/dbs/%s/colls/%s", "database", "container"), requestOptions);
containerResponse.subscribe(result -> {
    // retrieve the index transformation progress from the response headers
    String indexTransformationProgress = result.getResponseHeaders().get("x-ms-documentdb-collection-index-transformation-progress");
});

Node.js SDK'sını kullanma

ContainerDefinitionNode.js SDK'sının arabirimi (kullanımıyla ilgili bu Hızlı Başlangıç'a bakın) ve ile öğesini değiştirmenize ve eklemenize indexingMode veya kaldırmanıza includedPathsexcludedPathsolanak tanıyan bir indexingPolicy özelliği kullanıma sunar.

Kapsayıcının ayrıntılarını alma

const containerResponse = await client.database('database').container('container').read();

Dizin oluşturma modunu tutarlı olarak ayarlama

containerResponse.body.indexingPolicy.indexingMode = "consistent";

Uzamsal dizin de dahil olmak üzere eklenen yol ekleme

containerResponse.body.indexingPolicy.includedPaths.push({
    includedPaths: [
      {
        path: "/age/*",
        indexes: [
          {
            kind: cosmos.DocumentBase.IndexKind.Range,
            dataType: cosmos.DocumentBase.DataType.String
          },
          {
            kind: cosmos.DocumentBase.IndexKind.Range,
            dataType: cosmos.DocumentBase.DataType.Number
          }
        ]
      },
      {
        path: "/locations/*",
        indexes: [
          {
            kind: cosmos.DocumentBase.IndexKind.Spatial,
            dataType: cosmos.DocumentBase.DataType.Point
          }
        ]
      }
    ]
  });

Dışlanan yol ekleme

containerResponse.body.indexingPolicy.excludedPaths.push({ path: '/name/*' });

Kapsayıcıyı değişikliklerle güncelleştirme

const replaceResponse = await client.database('database').container('container').replace(containerResponse.body);

Bir kapsayıcıda dizin dönüştürme ilerleme durumunu izlemek için, özelliğini trueolarak ayarlayan populateQuotaInfo bir RequestOptions nesne geçirin ve ardından değeri yanıt üst bilgisinden x-ms-documentdb-collection-index-transformation-progress alın.

// retrieve the container's details
const containerResponse = await client.database('database').container('container').read({
    populateQuotaInfo: true
});
// retrieve the index transformation progress from the response headers
const indexTransformationProgress = replaceResponse.headers['x-ms-documentdb-collection-index-transformation-progress'];

Python SDK'yı kullanma

Python SDK V3'ünü kullanırken (kullanımıyla ilgili bu Hızlı Başlangıç'a bakın), kapsayıcı yapılandırması sözlük olarak yönetilir. Bu sözlükten dizin oluşturma ilkesine ve tüm özniteliklerine erişmek mümkündür.

Kapsayıcının ayrıntılarını alma

containerPath = 'dbs/database/colls/collection'
container = client.ReadContainer(containerPath)

Dizin oluşturma modunu tutarlı olarak ayarlama

container['indexingPolicy']['indexingMode'] = 'consistent'

Eklenen bir yol ve uzamsal dizin ile dizin oluşturma ilkesi tanımlama

container["indexingPolicy"] = {

    "indexingMode":"consistent",
    "spatialIndexes":[
                {"path":"/location/*","types":["Point"]}
             ],
    "includedPaths":[{"path":"/age/*","indexes":[]}],
    "excludedPaths":[{"path":"/*"}]
}

Dışarıda bırakılan bir yol ile dizin oluşturma ilkesi tanımlama

container["indexingPolicy"] = {
    "indexingMode":"consistent",
    "includedPaths":[{"path":"/*","indexes":[]}],
    "excludedPaths":[{"path":"/name/*"}]
}

Bileşik dizin ekleme

container['indexingPolicy']['compositeIndexes'] = [
                [
                    {
                        "path": "/name",
                        "order": "ascending"
                    },
                    {
                        "path": "/age",
                        "order": "descending"
                    }
                ]
                ]

Kapsayıcıyı değişikliklerle güncelleştirme

response = client.ReplaceContainer(containerPath, container)

Sonraki adımlar

Dizin oluşturma hakkında daha fazla bilgiyi aşağıdaki makalelerde bulabilirsiniz: