{"id":16437,"date":"2024-10-09T16:21:05","date_gmt":"2024-10-09T23:21:05","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=16437"},"modified":"2025-06-13T16:36:38","modified_gmt":"2025-06-13T23:36:38","slug":"couchbase-xattrs-vector-search","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/pt\/couchbase-xattrs-vector-search\/","title":{"rendered":"Aprimoramento do desempenho usando XATTRs para armazenamento e pesquisa de vetores"},"content":{"rendered":"

Com a introdu\u00e7\u00e3o do pesquisa vetorial<\/a>os usu\u00e1rios agora podem armazenar matrizes de vetores grandes<\/em>-(muitas vezes compostos por n\u00fameros aparentemente arbitr\u00e1rios) em seus documentos. Como esses dados n\u00e3o s\u00e3o necess\u00e1rios para a maioria das consultas padr\u00e3o, os usu\u00e1rios agora podem aproveitar atributos estendidos<\/em> (XATTRs), que fazem parte dos metadados do documento, para armazenar vetores e outros conte\u00fados volumosos. Ao fazer isso, o desempenho \u00e9 aprimorado, mantendo os dados pesados fora do caminho da consulta principal. Esta postagem explicar\u00e1 o que s\u00e3o XATTRs, destacar\u00e1 seus benef\u00edcios e demonstrar\u00e1 como eles podem ser usados na pesquisa.<\/p>\n

Onde est\u00e3o XATTRs?<\/span><\/h2>\n

Os XATTRs s\u00e3o os metadados de um documento que um usu\u00e1rio pode modificar ou alterar sem alterar o conte\u00fado do documento. Isso permite que o documento seja separado em duas partes. Os servi\u00e7os que exigem os documentos os buscar\u00e3o no Key Value Store (KV), que obt\u00e9m o conte\u00fado dos XATTRs somente quando necess\u00e1rio.<\/span><\/p>\n

Vejamos um exemplo em que o usu\u00e1rio est\u00e1 tentando indexar dados de hotel em que a estrutura do documento \u00e9 semelhante \u00e0 seguinte:<\/span><\/p>\n

{\r\n  \"title\": \"Gillingham (Kent)\",\r\n  \"name\": \"Medway Youth Hostel\",\r\n  \"endere\u00e7o\": \"Capstone Road, ME7 3JE\",\r\n  \"directions\": nulo,\r\n  \"phone\" (telefone): \"+44 870 770 5964\",\r\n  \"tollfree\": nulo,\r\n  \"e-mail\": nulo,\r\n  \"fax\": nulo,\r\n  \"url\": \"https:\/\/www.yha.org.uk\",\r\n  \"checkin\": nulo,\r\n  \"checkout\": nulo,\r\n  \"price\": nulo,\r\n  \"geo\": {\r\n    \"lat\": 51.35785,\r\n    \"lon\": 0.55818,\r\n    \"accuracy\" (precis\u00e3o): \"RANGE_INTERPOLATED\"\r\n  },\r\n  \"id\": 10025,\r\n  \"country\" (pa\u00eds): \"United Kingdom\" (Reino Unido),\r\n  \"city\" (cidade): \"Medway\",\r\n  \"state\": null,,\r\n  \"vacancy\": true,\r\n  \"description\": \"Albergue de ver\u00e3o com 40 leitos a cerca de 3 milhas de Gillingham, instalado em uma distinta Oast House convertida em um ambiente semi-rural.\",\r\n  \"description_vector\": [0.9293051,...(108 more float32s)...,0.41247833],\r\n  \"pets_ok\": true,\r\n  \"free_breakfast\": verdadeiro,\r\n  \"free_internet\": falso,\r\n  \"free_parking\": true\r\n}<\/pre>\n
Essa estrutura de documento inclui todos os campos necess\u00e1rios para um hotel, juntamente com uma descri\u00e7\u00e3o vetorizada usada para encontrar hot\u00e9is com descri\u00e7\u00f5es semelhantes. O vetor de descri\u00e7\u00e3o (linha 25), que \u00e9 um vetor de 110 dimens\u00f5es, ocupa cerca de 1.400 bytes, enquanto o restante do documento tem cerca de 1.400 bytes de tamanho.<\/span><\/p>\n
Em casos de uso comuns, quando um usu\u00e1rio executa uma consulta n\u00e3o vetorial usando o SQL++ sem um \u00edndice de cobertura, o documento inteiro \u00e9 obtido. Isso significa que, embora o vetor, que tem quase a metade do tamanho do documento, n\u00e3o seja necess\u00e1rio, ele ainda \u00e9 recuperado com o restante do documento, o que acaba desperdi\u00e7ando recursos.<\/span><\/p>\n
Imaginemos uma situa\u00e7\u00e3o em que o usu\u00e1rio n\u00e3o use XATTRs e tenha todos os dados dentro do conte\u00fado do documento e nenhum deles dentro de XATTRs. Qualquer servi\u00e7o, como consulta e pesquisa, que tente buscar documentos ter\u00e1 que processar todo o conte\u00fado do documento para obter o que deseja.<\/span><\/p>\n
\"\"<\/p>\n
Uma maneira melhor de estruturar esse documento seria armazenar o vetor como parte dos XATTRs. Isso significaria que os servi\u00e7os que procuram os dados n\u00e3o vetoriais s\u00f3 passar\u00e3o pelo conte\u00fado do documento n\u00e3o XATTRs, reduzindo pela metade o volume de dados transferidos.<\/span><\/p>\n
\"\"<\/p>\n
Os usu\u00e1rios podem at\u00e9 mesmo levar isso ao extremo adicionando outros campos pouco usados, como informa\u00e7\u00f5es geogr\u00e1ficas, detalhes de contato etc., tamb\u00e9m aos XATTRs. Isso reduz ainda mais a quantidade de dados desnecess\u00e1rios transferidos.<\/span><\/p>\n
\"\"<\/p>\n
Como indexar o Couchbase XATTRs<\/span><\/h2>\n
A partir do Couchbase Server 7.6.2, o servi\u00e7o de busca<\/a> oferece aos usu\u00e1rios a capacidade de ingerir dados presentes em XATTRs somente quando exigido pelo mapeamento do \u00edndice durante o processo de cria\u00e7\u00e3o do \u00edndice. Se os dados XATTRs n\u00e3o forem relevantes e um mapeamento XATTRs n\u00e3o estiver presente na defini\u00e7\u00e3o do \u00edndice, os usu\u00e1rios poder\u00e3o esperar uma taxa mais r\u00e1pida de ingest\u00e3o e indexa\u00e7\u00e3o de dados porque uma carga \u00fatil mais leve ser\u00e1 obtida do servi\u00e7o de dados.<\/span><\/p>\n
Vamos supor que um usu\u00e1rio tenha criado um \u00edndice que indexa o conte\u00fado dos XATTRs. A defini\u00e7\u00e3o do \u00edndice seria semelhante a esta, com XATTRs indexados nas linhas 10-27:<\/span><\/p>\n
{\r\n    \"name\": \"example-index\",\r\n    \"type\" (tipo): \"fulltext-index\",\r\n    \"params\": {\r\n    \"mapping\": {\r\n    \"default_mapping\": {\r\n    \"enabled\" (ativado): true,\r\n    \"dynamic\": true,\r\n    \"properties\" (propriedades): {\r\n      \"_$xattrs\": {\r\n        \"enabled\" (ativado): true,\r\n        \"dynamic\": true,\r\n        \"properties\" (propriedades): {\r\n        \"textField\": {\r\n        \"enabled\" (ativado): true,\r\n        \"dynamic\": false,\r\n        \"fields\": [\r\n            {\r\n            \"name\": \"textField\",\r\n            \"type\": \"text\",\r\n            \"store\": falso,\r\n            \"index\": true,\r\n            \"include_term_vectors\": false,\r\n            \"include_in_all\": falso,\r\n            \"docvalues\": falso\r\n            }\r\n        ]\r\n        }\r\n        }\r\n        }\r\n    }\r\n    },\r\n    \"default_type\": \"_default\",\r\n    \"default_analyzer\": \"standard\",\r\n    \"default_datetime_parser\": \"dateTimeOptional\",\r\n    \"default_field\": \"_all\",\r\n    \"store_dynamic\": falso,\r\n    \"index_dynamic\": true,\r\n    \"docvalues_dynamic\": falso\r\n    },\r\n    \"store\": {\r\n    \"indexType\": \"scorch\",\r\n    \"kvStoreName\": \"\"\r\n    },\r\n    \"doc_config\": {\r\n    \"mode\": \"type_field\",\r\n    \"type_field\": \"type\" (tipo),\r\n    \"docid_prefix_delim\": \"\",\r\n    \"docid_regexp\": \"\"\r\n    }\r\n    },\r\n    \"sourceType\": \"couchbase\",\r\n    \"sourceName\": \"sample-bucket\",\r\n    \"sourceUUID\": \"602c579bc2a74e67dc1f051eb769e702\",\r\n    \"sourceParams\": {},\r\n    \"planParams\": {\r\n    \"maxPartitionsPerPIndex\": 1024,\r\n    \"numReplicas\": 0,\r\n    \"indexPartitions\": 1\r\n    },\r\n    \"uuid\": \"\"\r\n}<\/pre>\n
Ap\u00f3s a cria\u00e7\u00e3o do \u00edndice usando uma defini\u00e7\u00e3o de \u00edndice como a acima, a pesquisa buscar\u00e1 todo o conte\u00fado do documento e o conte\u00fado dos XATTRs no servi\u00e7o de dados.<\/span><\/p>\n
\"\"<\/p>\n
Nesse caso, depois de buscar o conte\u00fado, o servi\u00e7o de busca combinar\u00e1 os dois em um \u00fanico documento. Os dados presentes nos XATTRs ser\u00e3o mapeados para o conte\u00fado do documento em um mapeamento de campo especial denominado _$xattrs<\/code><\/em>\u00a0durante o processo de indexa\u00e7\u00e3o.<\/span><\/p>\n
\"\"<\/p>\n
Para consultar os campos presentes no conte\u00fado dos XATTRs, deve-se observar que esse conte\u00fado ser\u00e1 colocado em um campo especial denominado _$xattrs<\/code> e a consulta deve refletir isso. H\u00e1 tamb\u00e9m uma restri\u00e7\u00e3o inerente ao tamanho do nome do campo XATTRs, que \u00e9 de 12 caracteres.<\/span><\/p>\n
Veja como fica a apar\u00eancia ao criar uma consulta para um documento de amostra com XATTRs<\/span>:<\/p>\n
{\r\n    \"explain\": true,\r\n    \"fields\": [\r\n        \"*\"\r\n    ],\r\n    \"highlight\": {},\r\n    \"query\" (consulta): {\r\n        \"query\" (consulta): \"_$xattrs.textField:*\"\r\n    },\r\n    \"size\": 10,\r\n    \"from\": 0\r\n}<\/pre>\n
Os XATTRs n\u00e3o se limitam ao armazenamento de vetores. Sempre que houver campos usados com pouca frequ\u00eancia, campos espec\u00edficos apenas para o servi\u00e7o de pesquisa ou campos volumosos, \u00e9 recomend\u00e1vel adicion\u00e1-los aos XATTRs. Dessa forma, os servi\u00e7os que n\u00e3o precisam desses campos precisam buscar menos dados do KV.\u00a0<\/span><\/p>\n
Pr\u00f3ximas etapas<\/span><\/h2>\n