Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / /

$substrBytes (agregação)

Nesta página

  • Definição
  • Comportamento
  • Exemplo
$substrBytes

Retorna a substring de uma string. A substring começa com o caractere no índice de bytes UTF-8 especificado (baseado em zero) na string e continua para o número de bytes especificados.

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

{ $substrBytes: [ <string expression>, <byte index>, <byte count> ] }
Campo
Tipo
Descrição
string expression
string

A string da qual a substring será extraída. string expression pode ser qualquer expressão válida desde que resolva para uma string. Para obter mais informações sobre expressões, consulte Operadores de Expressão.

Se o argumento for resolvido para um valor de null ou se referir a um campo ausente, $substrBytes retornará uma string vazia.

Se o argumento não se resolver em uma string ou null nem se referir a um campo ausente, $substrBytes retornará um erro.

byte index
número

Indica o ponto de partida da substring. byte index pode ser qualquer expressão válida, desde que resolva para um número inteiro não negativo ou número que possa ser representado como um número inteiro (como 2.0).

byte index não pode se referir a um índice inicial localizado no meio de um caractere UTF-8 de vários bytes.

byte count
número

Pode ser qualquer expressão válida, desde que resolva para um número inteiro não negativo ou número que possa ser representado como um número inteiro (como 2.0).

byte count não pode resultar em um índice final que esteja no meio de um caractere UTF-8.

O operador $substrBytes usa os índices de bytes codificados em UTF-8 em que cada ponto de código, ou caractere, pode usar entre um e quatro bytes para codificar.

Por exemplo, os caracteres US-ASCII são codificados usando um byte. Caracteres com diacríticos e caracteres alfabéticos latinos adicionais (caracteres latinos fora do alfabeto inglês) são codificados usando dois bytes. Caracteres chineses, tailandeses e coreanos normalmente exigem três bytes, e outros planos de unicode (emoji, símbolos matemáticos etc.) exigem quatro bytes.

É importante estar atento ao conteúdo do string expression porque fornecer um byte index ou byte count localizado no meio de um caractere UTF-8 resultará em um erro.

$substrBytes difere de $substrCP em que $substrBytes conta os bytes de cada caractere, enquanto $substrCP conta os pontos de código, ou caracteres, independentemente de quantos bytes um caractere utiliza.

Exemplo
Resultados
{ $substrBytes: [ "abcde", 1, 2 ] }
"bc"
{ $substrBytes: [ "Hello World!", 6, 5 ] }
"World"
{ $substrBytes: [ "cafétéria", 0, 5 ] }
"café"
{ $substrBytes: [ "cafétéria", 5, 4 ] }
"tér"
{ $substrBytes: [ "cafétéria", 7, 3 ] }

Erro com mensagem:

"Error: Invalid range, starting index is a UTF-8 continuation byte."

{ $substrBytes: [ "cafétéria", 3, 1 ] }

Erro com mensagem:

"Error: Invalid range, ending index is in the middle of a UTF-8 character."

Considere uma coleção inventory com os seguintes documentos:

{ "_id" : 1, "item" : "ABC1", quarter: "13Q1", "description" : "product 1" }
{ "_id" : 2, "item" : "ABC2", quarter: "13Q4", "description" : "product 2" }
{ "_id" : 3, "item" : "XYZ1", quarter: "14Q2", "description" : null }

A operação a seguir usa o operador $substrBytes para separar o valor quarter (contendo apenas caracteres US-ASCII de byte único) em um yearSubstring e um quarterSubstring. O campo quarterSubstring representa o resto da string a partir do byte index especificado depois de yearSubstring. Ele é calculado subtraindo o byte index do comprimento da string utilizando $strLenBytes.

db.inventory.aggregate(
[
{
$project: {
item: 1,
yearSubstring: { $substrBytes: [ "$quarter", 0, 2 ] },
quarterSubtring: {
$substrBytes: [
"$quarter", 2, { $subtract: [ { $strLenBytes: "$quarter" }, 2 ] }
]
}
}
}
]
)

A operação retorna os seguintes resultados:

{ "_id" : 1, "item" : "ABC1", "yearSubstring" : "13", "quarterSubtring" : "Q1" }
{ "_id" : 2, "item" : "ABC2", "yearSubstring" : "13", "quarterSubtring" : "Q4" }
{ "_id" : 3, "item" : "XYZ1", "yearSubstring" : "14", "quarterSubtring" : "Q2" }

Criar uma coleção food com os seguintes documentos:

db.food.insertMany(
[
{ "_id" : 1, "name" : "apple" },
{ "_id" : 2, "name" : "banana" },
{ "_id" : 3, "name" : "éclair" },
{ "_id" : 4, "name" : "hamburger" },
{ "_id" : 5, "name" : "jalapeño" },
{ "_id" : 6, "name" : "pizza" },
{ "_id" : 7, "name" : "tacos" },
{ "_id" : 8, "name" : "寿司sushi" }
]
)

A seguinte operação utiliza o operador $substrBytes para criar um menuCode de três bytes a partir do valor name :

db.food.aggregate(
[
{
$project: {
"name": 1,
"menuCode": { $substrBytes: [ "$name", 0, 3 ] }
}
}
]
)

A operação retorna os seguintes resultados:

{ "_id" : 1, "name" : "apple", "menuCode" : "app" }
{ "_id" : 2, "name" : "banana", "menuCode" : "ban" }
{ "_id" : 3, "name" : "éclair", "menuCode" : "éc" }
{ "_id" : 4, "name" : "hamburger", "menuCode" : "ham" }
{ "_id" : 5, "name" : "jalapeño", "menuCode" : "jal" }
{ "_id" : 6, "name" : "pizza", "menuCode" : "piz" }
{ "_id" : 7, "name" : "tacos", "menuCode" : "tac" }
{ "_id" : 8, "name" : "寿司sushi", "menuCode" : "寿" }

Dica

Veja também:

Voltar

$substr