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

Makale
08/18/2023

UYGULANANLAR: NoSQL

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 ilkeyi kendi özel dizin oluşturma ilkenizle geçersiz kılabilirsiniz.

Dekont

Bu makalede açıklanan dizin oluşturma ilkelerini güncelleştirme yöntemi yalnızca NoSQL için Azure Cosmos DB için geçerlidir. MongoDB için Azure Cosmos DB'de dizin oluşturma ve Apache Cassandra için Azure Cosmos DB'de İkincil dizin oluşturma hakkında bilgi edinin.

Dizin oluşturma ilkesi örnekleri

Aşağıda, JSON biçiminde gösterilen dizin oluşturma ilkelerine bazı örnekler verilmiştir. Bunlar Azure portalında JSON biçiminde kullanıma sunulur. 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/*"
        }
    ]
}

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": "/*"
        }
    ]
}

Dekont

Genellikle bir geri çevirme dizin oluşturma ilkesi kullanmanızı öneririz. Azure Cosmos DB, veri modelinize eklenebilecek tüm yeni özellikleri proaktif olarak dizine ekler.

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 için bu özelliklerde bileşik dizin gerekir. Sorguda birden çok özellikte sıralamanın yanı sıra filtreler varsa, birden fazla bileşik dizine ihtiyacınız olabilir.

Bileşik dizinler, birden çok filtreye veya hem filtreye hem de ORDER BY yan tümcesine sahip sorgular için performans avantajına da sahiptir.

Dekont

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. Bileşik yollar da büyük/küçük harfe duyarlıdır.

için tanımlanan bileşik dizin (ad asc, yaş desc)

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

Ad ve yaş üzerindeki bileşik dizin aşağıdaki sorgular için gereklidir:

Sorgu #1:

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 aşağıdaki sorgulardan yararlanır 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 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)

Siparişi 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ışla ama dizin oluşturmayı etkin tut

Yaşam Süresi (TTL) özelliğinin etkin olduğu ancak Azure Cosmos DB'yi saf anahtar-değer deposu olarak kullanmak için başka dizin gerekmeyen bu ilkeyi kullanabilirsiniz.

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

Dizin oluşturma yok

Bu ilke dizin oluşturmayı kapatır. olarak ayarlanırsa indexingModenone, kapsayıcıda 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ından
Azure CLI'yı kullanma
PowerShell’i 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.

Dekont

Dizin oluşturma ilkesini güncelleştirdiğinizde Azure Cosmos DB'ye yazma işlemleri kesintisiz olarak gerçekleştirilir. Dizin oluşturma dönüştürmeleri hakkında daha fazla bilgi edinin

Önemli

Bir dizinin kaldırılması hemen etkilenir, ancak dizin oluşturma dönüşümü gerektirdiği için yeni bir dizin eklemek biraz zaman alır. Bir dizini başka bir dizinle değiştirirken (örneğin, tek bir özellik dizinini bileşik dizinle değiştirirken) önce yeni dizini eklediğinizden emin olun ve dizin oluşturma ilkesinden önceki dizini kaldırmadan önce dizin dönüştürme işleminin tamamlanmasını bekleyin. Aksi takdirde bu, önceki dizini sorgulama becerinizi olumsuz etkiler ve önceki dizine başvuran tüm etkin iş yüklerini bozabilir.

Azure portal’ı kullanma

Azure Cosmos DB kapsayıcıları dizin oluşturma ilkelerini Azure portalının doğrudan düzenlemenizi sağlayan bir JSON belgesi olarak depolar.

Azure Portal oturum açın.
Yeni bir Azure Cosmos DB hesabı oluşturun veya mevcut bir hesabı seçin.
Veri Gezgini bölmesini açın ve üzerinde çalışmak istediğiniz kapsayıcıyı seçin.
Ölçek ve Ayarlar'ı seçin.
Dizin oluşturma ilkesi JSON belgesini, bu örneklerde gösterildiği gibi değiştirin.
Bitirdiğinizde Kaydet'i seçin.

Manage Indexing using Azure portal

Azure CLI'yi kullanma

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

PowerShell kullanma

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

ContainerProperties.NET SDK v3'ten gelen nesne, ve öğesini değiştirmenize, eklemenize IndexingMode veya kaldırmanıza IncludedPathsExcludedPathsolanak tanıyan bir IndexingPolicy özelliği kullanıma sunar. Daha fazla bilgi için bkz . Hızlı Başlangıç: .NET için NoSQL için Azure Cosmos DB istemci kitaplığı.

// Retrieve the container's details
ContainerResponse containerResponse = await client.GetContainer("database", "container").ReadContainerAsync();
// 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
SpatialPath spatialPath = new SpatialPath
{
    Path = "/locations/*"
};
spatialPath.SpatialTypes.Add(SpatialType.Point);
containerResponse.Resource.IndexingPolicy.SpatialIndexes.Add(spatialPath);
// 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.GetContainer("database", "container").ReplaceContainerAsync(containerResponse.Resource);

Dizin dönüştürme ilerleme durumunu izlemek için özelliğini trueolarak ayarlayan PopulateQuotaInfo bir RequestOptions nesne geçirin. Değeri yanıt üst bilgisinden x-ms-documentdb-collection-index-transformation-progress alın.

// retrieve the container's details
ContainerResponse containerResponse = await client.GetContainer("database", "container").ReadContainerAsync(new ContainerRequestOptions { PopulateQuotaInfo = true });
// retrieve the index transformation progress from the result
long indexTransformationProgress = long.Parse(containerResponse.Headers["x-ms-documentdb-collection-index-transformation-progress"]);

SDK V3 akıcı API'si, yeni bir kapsayıcı oluştururken özel dizin oluşturma ilkesi tanımlarken bu tanımı kısa ve verimli bir şekilde yazmanızı sağlar:

await client.GetDatabase("database").DefineContainer(name: "container", partitionKeyPath: "/myPartitionKey")
    .WithIndexingPolicy()
        .WithIncludedPaths()
            .Path("/*")
        .Attach()
        .WithExcludedPaths()
            .Path("/name/*")
        .Attach()
        .WithSpatialIndex()
            .Path("/locations/*", SpatialType.Point)
        .Attach()
        .WithCompositeIndex()
            .Path("/name", CompositePathSortOrder.Ascending)
            .Path("/age", CompositePathSortOrder.Descending)
        .Attach()
    .Attach()
    .CreateIfNotExistsAsync();

DocumentCollection.NET SDK v2'dennesne, ve ExcludedPathsöğesini değiştirmenize, eklemenize IndexingMode veya kaldırmanıza IncludedPaths olanak 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 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

DocumentCollection Java SDK'sından nesnesi ve setIndexingPolicy() yöntemlerini kullanıma sunargetIndexingPolicy(). değiştirdikleri IndexingPolicy nesne, dizin oluşturma modunu değiştirmenize ve dahil edilen ve dışlanan yolları eklemenize veya kaldırmanıza olanak tanır. Daha fazla bilgi için bkz . Hızlı Başlangıç: NoSQL için Azure Cosmos DB verilerini yönetmek için java uygulaması derleme.

// 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);
});

Bir kapsayıcıda dizin dönüştürme ilerleme durumunu izlemek için kota bilgilerinin doldurulma isteğinde bulunan bir RequestOptions nesneyi geçirin. Değeri yanıt üst bilgisinden x-ms-documentdb-collection-index-transformation-progress 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

ContainerDefinition Node.js SDK'sındangelen arabirim, ile excludedPathsöğesini değiştirmenize, eklemenize indexingMode veya kaldırmanıza includedPaths olanak tanıyan bir indexingPolicy özelliği kullanıma sunar. Daha fazla bilgi için bkz . Hızlı Başlangıç - Node.js için NoSQL için Azure Cosmos DB istemci kitaplığı.

Kapsayıcının ayrıntılarını alın:

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

Dizin oluşturma modunu tutarlı olacak şekilde ayarlayın:

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

Uzamsal dizin de dahil olmak üzere eklenen yol ekleyin:

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 ekle:

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

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

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. 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
Python SDK V4

Python SDK V3'lerini kullandığınızda kapsayıcı yapılandırması sözlük olarak yönetilir. Bu sözlükten dizin oluşturma ilkesine ve tüm özniteliklerine erişebilirsiniz. Daha fazla bilgi için bkz . Hızlı Başlangıç: Python için NoSQL için Azure Cosmos DB istemci kitaplığı.

Kapsayıcının ayrıntılarını alın:

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

Dizin oluşturma modunu tutarlı olacak şekilde ayarlayın:

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

Eklenen bir yol ve uzamsal dizin içeren bir dizin oluşturma ilkesi tanımlayın:

container["indexingPolicy"] = {

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

Dışarıda bırakılan bir yola sahip dizin oluşturma ilkesi tanımlayın:

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ştirin:

response = client.ReplaceContainer(containerPath, container)

Python SDK V4'lerini kullandığınızda kapsayıcı yapılandırması sözlük olarak yönetilir. Bu sözlükten dizin oluşturma ilkesine ve tüm özniteliklerine erişebilirsiniz.

Kapsayıcının ayrıntılarını alın:

database_client = cosmos_client.get_database_client('database')
container_client = database_client.get_container_client('container')
container = container_client.read()

Dizin oluşturma modunu tutarlı olacak şekilde ayarlayın:

indexingPolicy = {
    'indexingMode': 'consistent'
}

Eklenen bir yol ve uzamsal dizin içeren bir dizin oluşturma ilkesi tanımlayın:

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

Dışarıda bırakılan bir yola sahip dizin oluşturma ilkesi tanımlayın:

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

Bileşik dizin ekleme:

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

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

response = database_client.replace_container(container_client, container['partitionKey'], indexingPolicy)

Yanıt üst bilgilerinden dizin dönüştürme ilerleme durumunu alın:

container_client.read(populate_quota_info = True,
                      response_hook = lambda h,p: print(h['x-ms-documentdb-collection-index-transformation-progress']))

Sonraki adımlar

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

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

Dizin oluşturma ilkesi örnekleri

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

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

Yalnızca belirli bir özellik yolunda uzamsal dizin kullanma

Bileşik dizin oluşturma ilkesi örnekleri

için tanımlanan bileşik dizin (ad asc, yaş desc)

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

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

Tüm özellik yollarını dışla ama dizin oluşturmayı etkin tut

Dizin oluşturma yok

Dizin oluşturma ilkesi güncelleştiriliyor

Azure portal’ı kullanma

Azure CLI'yi kullanma

PowerShell kullanma

.NET SDK’yı kullanma

Java SDK'sını kullanma

Node.js SDK'sını kullanma

Python SDK'yı kullanma

Sonraki adımlar

Ek kaynaklar