Manage indexing policies in Azure Cosmos DB

A KÖVETKEZŐRE VONATKOZIK: NoSQL

Az Azure Cosmos DB-ben az adatok indexelése az egyes tárolókhoz definiált indexelési szabályzatok alapján történik. The default indexing policy for newly created containers enforces range indexes for any string or number. Ezt a szabályzatot a saját egyéni indexelési szabályzatával felülbírálhatja.

Megjegyzés:

A cikkben ismertetett indexelési szabályzatok frissítésének módja csak az Azure Cosmos DB for NoSQL-hez vonatkozik. További információ az Azure Cosmos DB for MongoDB-ben való indexelésről és a másodlagos indexelésről az Apache Cassandra-hoz készült Azure Cosmos DB-ben.

Indexelési szabályzat példái

Íme néhány példa az indexelési szabályzatokra a JSON-formátumukban. JSON formátumban vannak közzétéve az Azure Portalon. Ugyanezek a paraméterek az Azure CLI-vel vagy bármely SDK-val állíthatók be.

Letiltási szabályzat egyes tulajdonságelérési utak szelektív kizárásához

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

A tulajdonságútvonalak szelektív belefoglalására vonatkozó jóváhagyási szabályzat

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

Megjegyzés:

Általában azt javasoljuk, hogy használjon leiratkozási indexelési szabályzatot. Az Azure Cosmos DB proaktív módon indexel minden olyan új tulajdonságot, amely hozzáadható az adatmodellhez.

Térbeli index használata csak egy adott tulajdonságútvonalon

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

Összetett indexelési házirend-példák

Az egyes tulajdonságok elérési útjainak belefoglalása vagy kizárása mellett összetett indexet is megadhat. Több tulajdonsághoz záradékkal ORDER BY rendelkező lekérdezés végrehajtásához összetett indexre van szükség ezeken a tulajdonságokon. Ha a lekérdezés szűrőket és több tulajdonság szerinti rendezést is tartalmaz, akkor több összetett indexre is szükség lehet.

Az összetett indexek teljesítménybeli előnyt is élveznek a több szűrővel vagy szűrővel és ORDER BY záradékkal rendelkező lekérdezésekhez.

Megjegyzés:

Az összetett elérési utak implicitek /? , mivel a rendszer csak az adott elérési út skaláris értékét indexeli. A /* helyettesítő karakter nem támogatott az összetett útvonalakban. Nem szabad összetett elérési utat megadnia vagy /* megadnia/?. Az összetett útvonalak a kis- és nagybetűket is megkülönböztetik.

Összetett index definiálva (name asc, age desc)

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

A név és az életkor összetett indexe a következő lekérdezésekhez szükséges:

1. lekérdezés:

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

2. lekérdezés:

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

Ez az összetett index a következő lekérdezéseket biztosítja, és optimalizálja a szűrőket:

3. lekérdezés:

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

4. lekérdezés:

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

Összetett index definiálva (név ASC, age ASC) és (név ASC, age DESC)

Ugyanazon indexelési szabályzaton belül több összetett indexet is definiálhat.

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

Összetett index definiálva (név: ASC, age ASC)

Nem kötelező megadni a rendelést. Ha nincs megadva, a sorrend növekvő.

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

Az összes tulajdonság elérési útja kizárása, de az indexelés aktív marad

Ezt a szabályzatot akkor használhatja, ha az Élettartam (TTL) funkció aktív, de nincs szükség más indexekre az Azure Cosmos DB tiszta kulcs-érték tárolóként való használatához.

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

Nincs indexelés

Ez a szabályzat kikapcsolja az indexelést. Ha indexingMode be van állítva none, akkor nem állíthat be TTL-t a tárolón.

{
    "indexingMode": "none"
}

Indexelési szabályzat frissítése

Az Azure Cosmos DB-ben az indexelési szabályzat az alábbi módszerek bármelyikével frissíthető:

• From the Azure portal
• Az Azure CLI-vel
• Using PowerShell
• Az egyik SDK használata

Az indexelési szabályzat frissítése indexátalakítást indít el. Az átalakítás előrehaladása az SDK-kból is nyomon követhető.

Megjegyzés:

Az indexelési szabályzat frissítésekor az Azure Cosmos DB-be történő írások zavartalanok. További információ az átalakítások indexelésével kapcsolatban

Fontos

Az index eltávolítása azonnal hatással van, míg egy új index hozzáadása egy ideig tart, mivel az indexelési átalakítást igényel. Ha egy indexet lecserél egy másikra (például egy tulajdonságindexet összetett indexre cserél), először adja hozzá az új indexet, majd várja meg, amíg az indexátalakítás befejeződik , mielőtt eltávolítja az előző indexet az indexelési szabályzatból. Ellenkező esetben ez negatívan befolyásolja az előző index lekérdezésének képességét, és megszakíthatja az előző indexre hivatkozó aktív számítási feladatokat.

Use the Azure portal

Az Azure Cosmos DB-tárolók az indexelési szabályzatukat JSON-dokumentumként tárolják, amelyet az Azure Portal közvetlenül szerkeszthet.

1. Jelentkezzen be az Azure Portalra.

2. Hozzon létre egy új Azure Cosmos DB-fiókot, vagy válasszon ki egy meglévő fiókot.

3. Nyissa meg az Adatkezelő panelt, és válassza ki azt a tárolót, amelyen dolgozni szeretne.

4. Válassza a Méretezés &Gépház lehetőséget.

5. Módosítsa az indexelési szabályzat JSON-dokumentumát az alábbi példákban látható módon.

6. Ha végzett, válassza a Mentés lehetőséget.

Az Azure parancssori felületének használata

Ha egyéni indexelési szabályzattal rendelkező tárolót szeretne létrehozni, olvassa el a Tároló létrehozása egyéni indexszabályzattal a parancssori felület használatával című témakört.

Use PowerShell

Ha egyéni indexelési szabályzattal rendelkező tárolót szeretne létrehozni, olvassa el a Tároló létrehozása egyéni indexszabályzattal a PowerShell használatával című témakört.

A .NET SDK használata

.NET SDK V3

A ContainerProperties .NET SDK v3-ból származó objektum olyan tulajdonságot IndexingPolicy tesz elérhetővé, amely lehetővé teszi a módosítást, valamint a IndexingMode hozzáadást vagy eltávolítástIncludedPaths.ExcludedPaths További információ : Rövid útmutató: Azure Cosmos DB for NoSQL ügyfélkódtár a .NET-hez.

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

Az indexátalakítás előrehaladásának nyomon követéséhez adjon át egy RequestOptions objektumot, amely a tulajdonságot a PopulateQuotaInfo következőre trueállítja. Kérje le az értéket a x-ms-documentdb-collection-index-transformation-progress válaszfejlécből.

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

Az SDK V3 fluent API lehetővé teszi, hogy ezt a definíciót tömören és hatékonyan írja le, amikor egyéni indexelési szabályzatot határoz meg egy új tároló létrehozásakor:

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

.NET SDK V2

A DocumentCollection .NET SDK v2-ből származó objektum olyan tulajdonságot IndexingPolicy tesz elérhetővé, amely lehetővé teszi a módosítást, valamint a IndexingMode hozzáadást és az eltávolítástIncludedPaths.ExcludedPaths

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

Az indexátalakítás előrehaladásának nyomon követéséhez adjon át egy RequestOptions objektumot, amely a tulajdonságot a PopulateQuotaInfo következőre trueállítja.

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

A Java SDK használata

A DocumentCollection Java SDK-ból származó objektum elérhetővé teszi a metódusokat és setIndexingPolicy() a getIndexingPolicy() metódusokat. Az IndexingPolicy általuk manipulált objektum lehetővé teszi az indexelési mód módosítását, valamint a belefoglalt és kizárt elérési utak hozzáadását vagy eltávolítását. További információ : Rövid útmutató: Java-alkalmazás létrehozása az Azure Cosmos DB for NoSQL-adatok kezeléséhez.

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

A tároló indexátalakításának előrehaladásának nyomon követéséhez adjon át egy RequestOptions objektumot, amely a kvótaadatok feltöltését kéri. Kérje le az értéket a x-ms-documentdb-collection-index-transformation-progress válaszfejlécből.

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

A Node.js SDK használata

A ContainerDefinition Node.js SDK felülete egy olyan tulajdonságot indexingPolicy tesz elérhetővé, amely lehetővé teszi a módosítást, valamint a indexingMode hozzáadást vagy az eltávolítástincludedPaths.excludedPaths További információ: Rövid útmutató – Azure Cosmos DB for NoSQL ügyfélkódtár Node.js-hez.

A tároló adatainak lekérése:

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

Állítsa az indexelési módot konzisztensre:

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

Tartalmazott elérési út hozzáadása térbeli indexet is beleértve:

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

Kizárt elérési út hozzáadása:

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

Frissítse a tárolót a következő módosításokkal:

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

A tároló indexátalakításának előrehaladásának nyomon követéséhez adjon át egy RequestOptions objektumot, amely a tulajdonságot a populateQuotaInfo következőre trueállítja. Kérje le az értéket a x-ms-documentdb-collection-index-transformation-progress válaszfejlécből.

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

A Python SDK használata

Python SDK V3

A Python SDK V3 használatakor a tárolókonfiguráció szótárként lesz kezelve. Ebből a szótárból elérheti az indexelési szabályzatot és annak összes attribútumát. További információ : Rövid útmutató: Azure Cosmos DB for NoSQL ügyfélkódtár Pythonhoz.

A tároló adatainak lekérése:

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

Állítsa az indexelési módot konzisztensre:

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

Indexelési szabályzat definiálása belefoglalt elérési úttal és térbeli indexel:

container["indexingPolicy"] = {

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

Indexelési szabályzat definiálása kizárt elérési úttal:

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

Összetett index hozzáadása:

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

Frissítse a tárolót a következő módosításokkal:

response = client.ReplaceContainer(containerPath, container)

Python SDK V4

A Python SDK V4 használatakor a tárolókonfiguráció szótárként lesz kezelve. Ebből a szótárból elérheti az indexelési szabályzatot és annak összes attribútumát.

A tároló adatainak lekérése:

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

Állítsa az indexelési módot konzisztensre:

indexingPolicy = {
    'indexingMode': 'consistent'
}

Indexelési szabályzat definiálása belefoglalt elérési úttal és térbeli indexel:

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

Indexelési szabályzat definiálása kizárt elérési úttal:

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

Összetett index hozzáadása:

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

Frissítse a tárolót a következő módosításokkal:

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

Az indexátalakítás előrehaladásának lekérése a válaszfejlécekből:

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

További lépések

Az indexelésről az alábbi cikkekben olvashat bővebben:

• Indexelés áttekintése
• Indexelési szabályzat