Busca full-text com EF Core: SQL Server, PostgreSQL e SQLite
Objective
Where(a => a.Body.Contains("framework")) vira LIKE '%framework%'. Isso varre a
tabela, ignora formas de palavra e não dá nenhuma ordem de relevância. A busca
full-text é o recurso do banco feito para esse trabalho, e o EF Core 11 deixa o lado
SQL Server muito mais utilizável: o catálogo e o índice podem morar no modelo e ser
criados por migrations, e as funções com valor de tabela FREETEXTTABLE e
CONTAINSTABLE devolvem um rank pelo qual você pode ordenar.
Este concept mostra o mesmo recurso em três engines, porque o código não é portável
entre elas: SQL Server (EF Core 11), PostgreSQL (provider Npgsql) e SQLite (FTS5 por
SQL cru). Quais partes foram executadas importa. As seções de SQLite e de PostgreSQL
foram executadas com linhas reais: SQLite no EF Core 11.0.0, e PostgreSQL 18.7
(container descartável) com Npgsql 11.0.0 (o build estável que o NuGet publicou em
20 de novembro de 2026) e EF Core 11.0.0. O SQL de SQL Server foi gerado offline
(ToQueryString() e GenerateCreateScript(), sem servidor): prova o que o EF gera,
não o que um servidor devolve, e nada aqui rodou contra o SQL Server 2025. As regras
gerais de EF.Functions estão em ef-core-functions-and-database-specific-translation.
Use Cases
- Uma caixa de busca sobre artigos, tickets, produtos ou documentos em que "framework" também deve achar "Frameworks".
- Melhores resultados primeiro, com um score para ordenar; busca por prefixo, frases exatas e "esta palavra mas não aquela".
- Combinar as palavras exatas (full-text) com o significado (vetores) em uma só
consulta, veja
ef-core-vector-search-with-sql-server-2025.
Deep Dive
SQL Server: o catálogo e o índice pertencem ao modelo
Até o EF Core 10 o catálogo e o índice full-text eram SQL escrito à mão em uma migration. O EF Core 11 os modela:
csharpmodelBuilder.HasFullTextCatalog("ftCatalog");
modelBuilder.Entity<Article>()
.HasFullTextIndex(a => new { a.Title, a.Body })
.UseKeyIndex("PK_Articles")
.UseCatalog("ftCatalog");sqlCREATE FULLTEXT CATALOG [ftCatalog];
CREATE FULLTEXT INDEX ON [Articles]([Title], [Body])
KEY INDEX [PK_Articles] ON [ftCatalog];Duas coisas saíram de executar isso no 11.0.0:
UseKeyIndexé obrigatório. Sem ele a construção do modelo falha comFull-text index '{'Title', 'Body'}' on entity type 'Article' does not have a KEY INDEX configured.mais uma dica sobreUseKeyIndex. Segundo a documentação do SQL Server, o índice de chave é único, de uma só coluna e não anulável, e a chave primária é a escolha usual.- As colunas viram
nvarchar(450).TitleeBodysãonvarchar(max)por padrão, e assim que entram no índice full-text o DDL gerado diznvarchar(450). Essa é a convenção do SQL Server para qualquer propriedade string indexada (umHasIndex(x => x.Title)comum faz o mesmo). Para um título é inofensivo. Para o corpo de um artigo é um limite silencioso de 450 caracteres. Diga o que você quer:
csharpe.Property(a => a.Body).HasColumnType("nvarchar(max)");Com essa linha o DDL mantém nvarchar(max) e o mesmo CREATE FULLTEXT INDEX. O
componente Full-Text Search do SQL Server também precisa estar instalado no
servidor, e a disponibilidade varia por edição e hospedagem, então confira a sua.
SQL Server: predicados que filtram
EF.Functions.FreeText e EF.Functions.Contains existem há bastante tempo. Eles
devolvem um Boolean para o Where:
csharpdb.Articles.Where(a => EF.Functions.FreeText(a.Title, "entity framework"));
db.Articles.Where(a => EF.Functions.Contains(a.Title, "\"entity*\" AND \"core\""));sqlWHERE FREETEXT([a].[Title], N'entity framework')
WHERE CONTAINS([a].[Title], N'"entity*" AND "core"')FreeText recebe palavras simples e deixa o motor expandi-las em formas de palavra.
Contains recebe uma condição de busca com sintaxe própria: frases entre aspas,
AND/OR/NOT e * para prefixo. Nenhum dos dois dá um score, então você não
consegue ordenar por relevância com eles.
SQL Server: ranking com FreeTextTable e ContainsTable
As funções novas têm valor de tabela: devolvem linhas de chave e rank, e você faz o join de volta com a sua tabela.
csharpvar results = await db.Articles
.FreeTextTable<Article, int>("entity framework", a => a.Title)
.Join(db.Articles, f => f.Key, a => a.Id, (f, a) => new { a.Title, f.Rank })
.OrderByDescending(x => x.Rank)
.ToListAsync();sqlSELECT [a0].[Title], [f].[RANK] AS [Rank]
FROM FREETEXTTABLE([Articles], [Title], @p) AS [f]
INNER JOIN [Articles] AS [a0] ON [f].[KEY] = [a0].[Id]
ORDER BY [f].[RANK] DESCContainsTable<Article, int>(searchCondition, column, language, topN) tem o mesmo
formato, com a sintaxe "entity*" AND "core". Os argumentos opcionais são a coluna
(null pesquisa todas as colunas indexadas e emite *), um termo de idioma e um
topN que o SQL Server aplica dentro da função:
csharpdb.Articles.FreeTextTable<Article, int>("entity framework", null, "English", 5)sqlFROM FREETEXTTABLE([Articles], *, @p, LANGUAGE N'English', @p1) AS [f]O tipo de resultado é FullTextSearchResult<TKey>, um struct com exatamente Key e
Rank (um int). Ele não carrega a entidade. O exemplo da documentação do EF Core
11 lê r.Value dele, e isso não compila no 11.0.0, então o join de volta pela chave
mostrado acima é a forma que funciona. O tipo da chave precisa ser escrito
(<Article, int>), porque o compilador não consegue inferi-lo.
PostgreSQL: uma coluna tsvector e um índice GIN
O Npgsql modela a busca full-text como uma coluna tsvector gerada, um índice sobre
ela e operadores de consulta. A função de consulta vai dentro da lambda:
csharpmodelBuilder.Entity<Article>()
.HasGeneratedTsVectorColumn(a => a.SearchVector, "english", a => new { a.Title, a.Body })
.HasIndex(a => a.SearchVector).HasMethod("GIN");
db.Articles
.Where(a => a.SearchVector.Matches(EF.Functions.WebSearchToTsQuery("english", "entity framework -dapper")))
.OrderByDescending(a => a.SearchVector.Rank(EF.Functions.WebSearchToTsQuery("english", "entity framework -dapper")));sql"SearchVector" tsvector GENERATED ALWAYS AS (to_tsvector('english', "Title" || ' ' || "Body")) STORED NOT NULL
CREATE INDEX "IX_Articles_SearchVector" ON "Articles" USING GIN ("SearchVector");
WHERE a."SearchVector" @@ websearch_to_tsquery('english', 'entity framework -dapper')
ORDER BY ts_rank(a."SearchVector", websearch_to_tsquery('english', 'entity framework -dapper')) DESCExtrair a chamada para uma variável local (var q = EF.Functions.WebSearchToTsQuery(...),
depois Matches(q)) não funciona: lança InvalidOperationException: The 'WebSearchToTsQuery' method is not supported because the query has switched to client-evaluation. Com 44 linhas (quatro artigos reais, 40 de enchimento), a execução
devolveu "Entity Framework Core 11" (rank 0.1815) e "Frameworks everywhere" (0.1810)
para entity framework -dapper, e as mesmas três linhas para framework e frameworks.
websearch_to_tsquery aceita o que as pessoas digitam em uma caixa de busca (frases
entre aspas, -palavra, or) e não levantou erro com um entity and solto (duas
linhas de volta), então é a porta de entrada mais segura para texto do usuário. O
idioma ('english') decide o stemming e as stop words, e precisa casar com o conteúdo.
Com SET enable_seqscan = off, o EXPLAIN mostrou um Bitmap Index Scan no índice GIN.
SQLite: FTS5, com uma tabela virtual e SQL cru
O SQLite não tem mapeamento do EF para busca full-text, mas o motor tem FTS5
embutido. A parte do EF Core é executar o seu SQL. A tabela é uma tabela FTS5 de
conteúdo externo que aponta para Articles, mantida em sincronia por três triggers
(o de update apaga a linha antiga do índice e insere a nova):
sqlCREATE VIRTUAL TABLE ArticlesFts USING fts5(
Title, Body, content='Articles', content_rowid='Id',
tokenize='unicode61 remove_diacritics 2');
CREATE TRIGGER Articles_ai AFTER INSERT ON Articles BEGIN
INSERT INTO ArticlesFts(rowid, Title, Body) VALUES (new.Id, new.Title, new.Body);
END;
CREATE TRIGGER Articles_ad AFTER DELETE ON Articles BEGIN
INSERT INTO ArticlesFts(ArticlesFts, rowid, Title, Body)
VALUES ('delete', old.Id, old.Title, old.Body);
END;
-- Articles_au (AFTER UPDATE): a mesma linha 'delete', depois o INSERT novoEm um projeto real esse SQL vai em uma migration com migrationBuilder.Sql(...),
porque o modelo nunca enxerga ArticlesFts (a execução usou ExecuteSql). A
consulta é um SqlQuery<T> sobre um join, ordenada por bm25:
csharppublic record Hit(int Id, string Title, double Score);
var hits = db.Database.SqlQuery<Hit>($"""
SELECT a.Id AS Id, a.Title AS Title, -bm25(ArticlesFts, 10.0, 1.0) AS Score
FROM ArticlesFts
JOIN Articles AS a ON a.Id = ArticlesFts.rowid
WHERE ArticlesFts MATCH {match}
ORDER BY bm25(ArticlesFts, 10.0, 1.0)
""").ToList();bm25 devolve um número negativo em que menor é melhor, então a consulta ordena de
forma crescente e inverte o sinal para exibir. Os dois pesos fazem um acerto em
Title valer dez vezes um acerto em Body. Com 44 artigos na tabela (quatro reais e
40 linhas de enchimento), a execução imprimiu:
MATCH |
Resultado (score) |
|---|---|
entity framework |
1 "Entity Framework Core 11" (11.058), 3 "Dapper versus EF Core" (5.962) |
entit* (prefixo) |
as mesmas duas linhas, a 1 primeiro |
"entity framework" (frase) |
as mesmas duas linhas |
core NOT dapper |
só a 1 |
title:core (uma coluna) |
3 (5.620), 1 (5.529) |
configuracao |
"Configuração do banco" (6.679), graças ao remove_diacritics |
Quatro comportamentos para conhecer antes de ir para produção:
- Os triggers não são opcionais. Uma tabela de conteúdo externo não acompanha a
tabela para a qual aponta. Contando os acertos direto na tabela virtual
(
SELECT count(*) FROM ArticlesFts WHERE ArticlesFts MATCH 'pasta'), umExecuteDeletedo artigo levou a contagem de 1 para 0 com o trigger de delete no lugar, e de 1 para 1 sem ele. A entrada velha continua no índice, e oJOINde volta comArticlesé o que a esconde da consulta acima. Operações em massa comoExecuteDeleteeExecuteUpdatepulam o change tracker, mas não os triggers do banco, e por isso os triggers são a camada certa. - Tabelas minúsculas dão score zero. Na primeira execução a tabela tinha só
quatro linhas, cada termo aparecia em metade delas, e todo score de
bm25saiu0.000. Scores precisam de um corpus: a ordenação só apareceu com o enchimento. MATCHtem sintaxe própria, e entrada ruim lança exceção. Passarentity ANDde uma caixa de busca levantouSqliteException: SQLite Error 1: 'fts5: syntax error near ""'. A correção testada é transformar o texto do usuário em uma frase, cercando-o de aspas duplas e dobrando qualquer aspa interna:static string Quote(string s) => "\"" + s.Replace("\"", "\"\"") + "\"";.Quote("entity AND")não devolveu linhas nem exceção, e uma entrada hostil (a" OR "b) virou a frase inofensiva"a"" OR ""b". O preço: os usuários perdem operadores e prefixos, a menos que você os devolva.- Não é
LIKE.EF.Functions.Like(a.Body, "%framework%")casou uma linha por substring pura emBody, sem ranking e sem índice. O FTS5 casou duas porque pesquisouTitleeBodye tokenizou as palavras.
O SQL Server tem a mesma armadilha: CONTAINS falha com uma condição malformada,
FREETEXT é mais tolerante (documentação do SQL Server, não executado aqui).
Trade-offs
- Três engines, três APIs. Nada neste concept é portável. Um recurso que precisa rodar em SQL Server e PostgreSQL exige uma interface sua com duas implementações ou um serviço de busca fora do banco.
- O índice não é instantâneo em todo lugar. O SQL Server popula um índice full-text com um processo próprio, então uma linha recém-inserida pode não ser pesquisável ainda (comportamento documentado do SQL Server, não executado aqui). Triggers e colunas geradas, como nos exemplos de SQLite e PostgreSQL, mantêm o índice transacional com a escrita.
- O idioma faz parte do índice. Stemming e stop words dependem do idioma configurado; um catálogo em português com configuração em inglês parece "instável".
- Scores não são comparáveis. O rank do SQL Server, o
ts_rankdo PostgreSQL e obm25do SQLite usam escalas diferentes: ordene por eles, não fixe um limite. nvarchar(450)pode truncar dados. Revise o DDL de qualquer entidade indexada.- Quando o banco não basta. Tolerância a erros de digitação, facetas e sinônimos
sobre milhões de documentos são para engines dedicadas como Meilisearch ou
Elasticsearch, ao custo de uma segunda cópia dos dados para manter em sincronia
(
full-text-and-vector-search-indexes, na trilha de system design, compara as duas).