$indexOfArray (agregação)

Definição

$indexOfArray

Pesquisar uma matriz para uma ocorrência de um valor especificado e retorna o índice da matriz (baseado em zero) da primeira ocorrência. Se o valor não for encontrado, retorna -1.

$indexOfArray tem a seguintesintaxe de expressão do operador :

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

Campo	Tipo	Descrição
<array>	string	Pode ser qualquer expressão válida desde que ela resolva para uma array. Para mais informações sobre expressões, consulte Expressões. Se a expressão de array for resolvida com um valor de null ou se referir a um campo ausente, $indexOfArray retornará null. Se a expressão do array não resolver um array ou null nem se referir a um campo ausente, $indexOfArray resultará em um erro.
<search value>	string	Pode ser qualquer expressão válida. Para mais informações sobre expressões, consulte Expressões.
<start>	inteiro	Opcional. Um inteiro ou um número que pode ser representado como inteiros (como 2.0), que especifica a posição inicial do índice para a pesquisa. Pode ser qualquer expressão válida que resolva um número integral não negativo. Se não for especificado, a posição do índice inicial para a pesquisa é o início da string.
<end>	inteiro	Opcional. Um inteiro ou um número que pode ser representado como inteiros (como 2.0), que especifica a posição final do índice para a pesquisa. Pode ser qualquer expressão válida que resolva um número integral não negativo. Se você especificar um valor de índice <end>, também deverá especificar um valor de índice <start>; caso contrário, $indexOfArray usará o valor <end> como o valor de índice <start> em vez do valor <end>. Se não for especificado, a posição do índice final para a pesquisa é o final da string.

Comportamento

Se <search expression> for encontrado várias vezes dentro de <array expression>, então $indexOfArray retornará o índice do primeiro <search expression> a partir da posição inicial do índice.

$indexOfArray retornará null:

• Se <array expression> for nulo, ou

• Se <array expression> se referir a um campo inexistente no documento de entrada.

$indexOfArray retorna um erro:

• Se <array expression> não for uma matriz e não nulo, ou

• Se <start> ou <end> for um número inteiro negativo (ou um valor que pode ser representado como um número inteiro negativo, como -5,0).

$indexOfArray retornará -1:

• Se a <expressão de pesquisa> não for encontrada na matriz, ou

• Se <start> for um número maior que <end>, ou

• Se <start> for um número maior que o comprimento da array.

Exemplo

O exemplo utiliza esta coleção inventory :

db.inventory.insertMany( [
   { _id: 0, items: [ "one", "two", "three" ] },
   { _id: 1, items: [ 1, 2, 3 ] },
   { _id: 2, items: [ 1, 2, 3, 2 ] },
   { _id: 3, items: [ null, null, 2 ] },
   { _id: 4, items: [ 2, null, null, 2 ] },
   { _id: 5, items: null },
   { _id: 6, amount: 3 }
] )

O exemplo a seguir utiliza $indexOfArray para localizar 2 na array items:

db.inventory.aggregate( [ {
   $project: {
      index: { $indexOfArray: [ "$items", 2 ] }
   }
} ] )

O exemplo retorna:

• O primeiro índice de matriz para o valor 2 em cada matriz items, se encontrado. Os índices da matriz começam em 0.

• -1 para o índice se 2 não estiver no array items.

• null para o índice se items não for uma array ou items não existir.

Saída de exemplo:

[
   { _id: 0, index: -1 },
   { _id: 1, index: 1 },
   { _id: 2, index: 1 },
   { _id: 3, index: 2 },
   { _id: 4, index: 0 },
   { _id: 5, index: null },
   { _id: 6, index: null }
]