MongoDB $indexOfArray

No MongoDB, o $indexOfArray o operador de pipeline de agregação pesquisa uma ocorrência de um valor especificado em uma matriz e retorna o índice da matriz da primeira ocorrência.

Sintaxe

A sintaxe fica assim:

{ $indexOfArray: [ <array expression>, <search expression>, <start>, <end> ] }

Onde:

<array expression> é a matriz a ser pesquisada.
<search expression> é o valor que você deseja encontrar na matriz.
<start> é um argumento opcional que especifica um ponto de partida para pesquisar na matriz. Pode ser qualquer expressão válida que resolva para um número inteiro não negativo.
<end> é um argumento opcional que especifica uma posição de índice final para a pesquisa. Pode ser qualquer expressão válida que resolva para um número inteiro não negativo.

No MongoDB, os arrays são baseados em zero, então a contagem de índice começa em zero (0 ).

Se o valor especificado não for encontrado, $indexOfArray retorna -1 .

Se houver várias instâncias do valor especificado, apenas a primeira será retornada.

Exemplo

Suponha que tenhamos uma coleção chamada products com os seguintes documentos:

{ "_id" : 1, "prod" : "Bat", "sizes" : [ "XS", "M", "L" ] }
{ "_id" : 2, "prod" : "Hat", "sizes" : [ "XS", "S", "L", "XL" ] }
{ "_id" : 3, "prod" : "Cap", "sizes" : [ "XXS", "XS", "M", "XL" ] }
{ "_id" : 4, "prod" : "Zap", "sizes" : [ 10, 12, 15 ] }
{ "_id" : 5, "prod" : "Tap", "sizes" : [ 15, 16, 20 ] }

Aqui está um exemplo de aplicação de $indexOfArray a esses documentos:

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 1, 2, 3, 4, 5 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", "XS" ] }
          }
     }
   ]
)

Resultado:

{ "sizes" : [ "XS", "M", "L" ], "result" : 0 }
{ "sizes" : [ "XS", "S", "L", "XL" ], "result" : 0 }
{ "sizes" : [ "XXS", "XS", "M", "XL" ], "result" : 1 }
{ "sizes" : [ 10, 12, 15 ], "result" : -1 }
{ "sizes" : [ 15, 16, 20 ], "result" : -1 }

Nos dois primeiros documentos, o valor da pesquisa foi encontrado na posição 0 (matrizes são baseadas em zero).

No terceiro documento, foi encontrado na posição 1 . Observe que a pesquisa foi por uma correspondência exata. Não retornou a posição 0 , mesmo que o valor na posição 0 contém o valor de pesquisa (ou seja, XXS contém XS ).

O valor de pesquisa não foi encontrado nos dois últimos documentos e, portanto, -1 foi devolvido.

Aqui está outro exemplo, exceto que desta vez procuramos um valor numérico:

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 1, 2, 3, 4, 5 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", 15 ] }
          }
     }
   ]
)

Resultado:

{ "sizes" : [ "XS", "M", "L" ], "result" : -1 }
{ "sizes" : [ "XS", "S", "L", "XL" ], "result" : -1 }
{ "sizes" : [ "XXS", "XS", "M", "XL" ], "result" : -1 }
{ "sizes" : [ 10, 12, 15 ], "result" : 2 }
{ "sizes" : [ 15, 16, 20 ], "result" : 0 }

Especifique uma posição inicial

Você pode fornecer um terceiro argumento para especificar uma posição de índice inicial para a pesquisa.

Exemplo:

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 4, 5 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", 15, 1 ] }
          }
     }
   ]
)

Resultado:

{ "sizes" : [ 10, 12, 15 ], "result" : 2 }
{ "sizes" : [ 15, 16, 20 ], "result" : -1 }

Neste caso, a expressão de busca não foi encontrada no segundo documento (documento 5). Isso ocorre porque iniciamos a pesquisa na posição 1 , e embora esse documento contenha a expressão de pesquisa, está na posição 0 (antes da posição inicial para a busca).

Especifique uma posição final

Você também pode fornecer um quarto argumento para especificar a posição final do índice para a pesquisa.

Se você fornecer esse argumento, também precisará fornecer uma posição inicial. Se isso não for feito, esse argumento será interpretado como o ponto de partida.

Exemplo:

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 1, 2, 3 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", "XS", 0, 1 ] }
          }
     }
   ]
)

Resultado:

{ "sizes" : [ "XS", "M", "L" ], "result" : 0 }
{ "sizes" : [ "XS", "S", "L", "XL" ], "result" : 0 }
{ "sizes" : [ "XXS", "XS", "M", "XL" ], "result" : -1 }

O terceiro documento retornou -1 o que significa que a expressão de pesquisa não foi encontrada.

Aqui está o que acontece se incrementarmos a posição final do índice em 1:

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 1, 2, 3 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", "XS", 0, 2 ] }
          }
     }
   ]
)

Resultado:

{ "sizes" : [ "XS", "M", "L" ], "result" : 0 }
{ "sizes" : [ "XS", "S", "L", "XL" ], "result" : 0 }
{ "sizes" : [ "XXS", "XS", "M", "XL" ], "result" : 1 }

Desta vez, o valor foi incluído e sua posição de índice foi retornada.

Matrizes vazias

Pesquisar uma matriz vazia retorna -1 .

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 6 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", "XS" ] }
          }
     }
   ]
)

Resultado:

{ "sizes" : [ ], "result" : -1 }

Campos ausentes

Se o campo não estiver no documento, $indexOfArray retorna null .

Suponha que temos o seguinte documento:

{ "_id" : 8, "prod" : "Map" }

Veja o que acontece quando aplicamos $indexOfArray :

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 8 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", "XS" ] }
          }
     }
   ]
)

Resultado:

{ "result" : null }

Valores nulos

Se a expressão de matriz for null (em vez de uma matriz), $indexOfArray retorna null .

Suponha que temos o seguinte documento:

{ "_id" : 7, "prod" : "Lap", "sizes" : null }

Veja o que acontece quando aplicamos $indexOfArray :

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 7 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", "XS" ] }
          }
     }
   ]
)

Resultado:

{ "sizes" : null, "result" : null }

No entanto, quando a expressão de pesquisa é null , o resultado é -1 , a menos que a expressão de matriz também seja null ou seu campo está faltando:

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 1, 2, 3, 4, 5, 6, 7, 8 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", null ] }
          }
     }
   ]
)

Resultado:

{ "sizes" : [ "XS", "M", "L" ], "result" : -1 }
{ "sizes" : [ "XS", "S", "L", "XL" ], "result" : -1 }
{ "sizes" : [ "XXS", "XS", "M", "XL" ], "result" : -1 }
{ "sizes" : [ 10, 12, 15 ], "result" : -1 }
{ "sizes" : [ 15, 16, 20 ], "result" : -1 }
{ "sizes" : [ ], "result" : -1 }
{ "sizes" : null, "result" : null }
{ "result" : null }

Tipo de dados incorreto

Se a expressão de matriz for o tipo de dados incorreto, $indexOfArray retorna um erro.

Suponha que temos o seguinte documento:

{ "_id" : 9, "prod" : "Box", "sizes" : "XXL" }

Veja o que acontece quando aplicamos $indexOfArray a esse documento:

db.products.aggregate(
   [
     { $match: { _id: { $in: [ 9 ] } } },
     {
       $project:
          {
            _id: 0,
            sizes: 1,
            result: { $indexOfArray: [ "$sizes", "XXL" ] }
          }
     }
   ]
)

Resultado:

uncaught exception: Error: command failed: {
	"ok" : 0,
	"errmsg" : "$indexOfArray requires an array as a first argument, found: string",
	"code" : 40090,
	"codeName" : "Location40090"
} : aggregate failed :
[email protected]/mongo/shell/utils.js:25:13
[email protected]/mongo/shell/assert.js:18:14
[email protected]/mongo/shell/assert.js:639:17
[email protected]/mongo/shell/assert.js:729:16
[email protected]/mongo/shell/db.js:266:5
[email protected]/mongo/shell/collection.js:1058:12
@(shell):1:1

Como a mensagem de erro indica, $indexOfArray requires an array as a first argument .