Správa zásad indexování ve službě Azure Cosmos DB

PLATÍ PRO: NoSQL

Ve službě Azure Cosmos DB se data indexují podle zásad indexování definovaných pro každý kontejner. Výchozí zásady indexování pro nově vytvořené kontejnery u všech řetězců a čísel vynucují indexy rozsahu. Tuto zásadu můžete přepsat vlastními zásadami indexování.

Příklady zásad indexování

Tady je několik příkladů zásad indexování zobrazených ve formátu JSON. Zobrazují se na webu Azure Portal ve formátu JSON. Stejné parametry je možné nastavit prostřednictvím Azure CLI nebo jakékoli sady SDK.

Zásady odhlášení pro selektivní vyloučení některých cest vlastností

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

Zásady výslovného souhlasu se selektivním zahrnutím některých cest vlastností

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

Použití prostorového indexu pouze na konkrétní cestě vlastnosti

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

Příklady zásad indexování vektorů

Kromě zahrnutí nebo vyloučení cest pro jednotlivé vlastnosti můžete také zadat vektorový index. Obecně platí, že indexy vektorů by měly být zadány vždy, když VectorDistance se systémová funkce používá k měření podobnosti mezi vektorem dotazu a vektorovou vlastností.

{
    "indexingMode": "consistent",
    "automatic": true,
    "includedPaths": [
        {
            "path": "/*"
        }
    ],
    "excludedPaths": [
        {
            "path": "/_etag/?"
        },
        {
            "path": "/vector/*"
        }
    ],
    "vectorIndexes": [
        {
            "path": "/vector",
            "type": "quantizedFlat"
        }
    ]
}

Můžete definovat následující typy zásad indexu vektorů:

quantizedFlat Typy indexů flat využívají index služby Azure Cosmos DB k ukládání a čtení jednotlivých vektorů při hledání vektorů. Vektorové vyhledávání s indexem jsou vyhledávání hrubou flat silou a vytvářejí 100% přesnost. Existují však omezení 505 dimenzí vektorů na plochém indexu.

Index quantizedFlat ukládá do indexu kvantované nebo komprimované vektory. Vektorové vyhledávání s indexem quantizedFlat jsou také hrubou silou hledání, ale jejich přesnost může být o něco menší než 100 %, protože vektory jsou před přidáním do indexu kvantovány. Hledání vektorů by quantized flat ale mělo mít nižší latenci, vyšší propustnost a nižší náklady na RU než vektorové vyhledávání v indexu flat . Tato možnost je vhodná pro scénáře, ve kterých používáte filtry dotazů k zúžení vektorového vyhledávání na relativně malou sadu vektorů.

Index diskANN je samostatný index definovaný speciálně pro vektory využívající DiskANN, sadu vysoce výkonných algoritmů indexování vektorů vyvinutých společností Microsoft Research. Indexy DiskANN můžou nabízet některé dotazy s nejnižší latencí, dotazy s nejvyšším dotazem za sekundu (QPS) a dotazy s nejnižšími náklady na RU s vysokou přesností. Vzhledem k tomu, že diskANN je přibližný index nejbližších sousedů (ANN), může být přesnost nižší než quantizedFlat nebo flat.

Příklady složených zásad indexování

Kromě zahrnutí nebo vyloučení cest pro jednotlivé vlastnosti můžete také zadat složený index. Chcete-li provést dotaz, který má ORDER BY klauzuli pro více vlastností, je pro tyto vlastnosti vyžadován složený index . Pokud dotaz obsahuje filtry spolu s řazením více vlastností, možná budete potřebovat více než jeden složený index.

Složené indexy mají také výhodu výkonu pro dotazy, které mají více filtrů, nebo filtr i klauzuli ORDER BY.

Složený index definovaný pro (name asc, age desc)

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

Složený index pro název a věk se vyžaduje pro následující dotazy:

Dotaz č. 1:

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

Dotaz č. 2:

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

Tento složený index přináší následující dotazy a optimalizuje filtry:

Dotaz č. 3:

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

Dotaz č. 4:

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

Složený index definovaný pro (název ASC, věk ASC) a (název ASC, age DESC)

V rámci stejné zásady indexování můžete definovat více složených indexů.

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

Složený index definovaný pro (název ASC, věk ASC)

Je volitelné zadat objednávku. Pokud není zadáno, pořadí je vzestupné.

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

Vyloučit všechny cesty vlastností, ale zachovat aktivní indexování

Tuto zásadu můžete použít, pokud je aktivní funkce TTL (Time-to-Live), ale k použití služby Azure Cosmos DB jako čistě úložiště klíč-hodnota nejsou potřeba žádné další indexy.

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

Bez indexování

Tato zásada vypne indexování. Pokud indexingMode je nastavená hodnota none, nemůžete v kontejneru nastavit hodnotu TTL.

{
    "indexingMode": "none"
}

Aktualizace zásad indexování

Ve službě Azure Cosmos DB je možné zásady indexování aktualizovat pomocí některé z následujících metod:

• Pomocí webu Azure Portal
• Použití Azure CLI
• Pomocí prostředí PowerShell
• Použití jedné ze sad SDK

Aktualizace zásad indexování aktivuje transformaci indexu. Průběh této transformace lze také sledovat ze sad SDK.

Použití portálu Azure Portal

Kontejnery Azure Cosmos DB ukládají své zásady indexování jako dokument JSON, který vám azure Portal umožňuje přímo upravovat.

1. Přihlaste se k portálu Azure.

2. Vytvořte nový účet služby Azure Cosmos DB nebo vyberte existující účet.

3. Otevřete podokno Průzkumník dat a vyberte kontejner, na který chcete pracovat.

4. Vyberte Škálovat a nastavení.

5. Upravte dokument JSON zásad indexování, jak je znázorněno v těchto příkladech.

6. Až budete hotovi, zvolte tlačítko Uložit.

Použití Azure CLI

Pokud chcete vytvořit kontejner s vlastní zásadou indexování, přečtěte si téma Vytvoření kontejneru s vlastními zásadami indexu pomocí rozhraní příkazového řádku.

Použití PowerShellu

Pokud chcete vytvořit kontejner s vlastní zásadou indexování, přečtěte si téma Vytvoření kontejneru s vlastními zásadami indexu pomocí PowerShellu.

Použití sady .NET SDK

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

// 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"]);

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();

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

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

Použití sady Java SDK

Objekt DocumentCollection ze sady Java SDK zveřejňuje getIndexingPolicy() metody a setIndexingPolicy() metody. Objekt IndexingPolicy , se kterým manipuluje, umožňuje změnit režim indexování a přidat nebo odebrat zahrnuté a vyloučené cesty. Další informace najdete v tématu Rychlý start: Vytvoření aplikace Java pro správu dat Azure Cosmos DB for NoSQL.

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

Pokud chcete sledovat průběh transformace indexu v kontejneru, předejte RequestOptions objekt, který požaduje naplnění informací o kvótách. Načtěte hodnotu z hlavičky x-ms-documentdb-collection-index-transformation-progress odpovědi.

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

Použití sady Node.js SDK

Rozhraní ContainerDefinition ze sady Node.js SDK zveřejňuje indexingPolicy vlastnost, která umožňuje změnit indexingMode a přidat nebo odebrat includedPaths a excludedPaths. Další informace najdete v tématu Rychlý start – Klientská knihovna Azure Cosmos DB for NoSQL pro Node.js.

Načtěte podrobnosti kontejneru:

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

Nastavte režim indexování na konzistentní:

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

Přidání zahrnuté cesty včetně prostorového indexu:

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

Přidat vyloučenou cestu:

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

Aktualizujte kontejner změnami:

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

Chcete-li sledovat průběh transformace indexu v kontejneru, předejte RequestOptions objekt, který nastaví populateQuotaInfo vlastnost na true. Načtěte hodnotu z hlavičky x-ms-documentdb-collection-index-transformation-progress odpovědi.

// 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'];

Přidejte složený index:

 console.log("create container with composite indexes");
  const containerDefWithCompositeIndexes = {
    id: "containerWithCompositeIndexingPolicy",
    indexingPolicy: {
      automatic: true,
      indexingMode: IndexingMode.consistent,
      includedPaths: [
        {
          path: "/*",
        },
      ],
      excludedPaths: [
        {
          path: '/"systemMetadata"/*',
        },
      ],
      compositeIndexes: [
        [
          { path: "/field", order: "ascending" },
          { path: "/key", order: "ascending" },
        ],
      ],
    },
  };
  const containerWithCompositeIndexes = (
    await database.containers.create(containerDefWithCompositeIndexes)
  ).container;

Použití sady Python SDK

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

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

container["indexingPolicy"] = {

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

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

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

response = client.ReplaceContainer(containerPath, container)

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

indexingPolicy = {
    'indexingMode': 'consistent'
}

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

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

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

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

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

Další kroky

Další informace o indexování najdete v následujících článcích:

• Přehled indexování
• Zásady indexování