TOPO (Transact-SQL)

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada SQL do AzureAzure Synapse AnalyticsAnalytics Platform System (PDW)ponto de extremidade de análise SQL no Microsoft FabricWarehouse no Microsoft Fabricbanco de dados SQL no Microsoft Fabric

Limita as linhas retornadas em um conjunto de resultados de consulta a um número especificado de linhas ou porcentagem de linhas no SQL Server. Quando você usa TOP com a cláusula ORDER BY, o conjunto de resultados é limitado ao primeiro n número de linhas ordenadas. Caso contrário, TOP retorna a primeira n número de linhas em uma ordem indefinida. Use esta cláusula para especificar o número de linhas retornadas de uma instrução SELECT. Ou, use TOP para especificar as linhas afetadas por uma instrução INSERT, UPDATE, MERGEou DELETE.

Transact-SQL convenções de sintaxe

Sintaxe

Sintaxe do SQL Server e do Banco de Dados SQL do Azure:

[
    TOP (expression) [ PERCENT ]
    [ WITH TIES ]
]

Sintaxe do Azure Synapse Analytics and Analytics Platform System (PDW):

[
    TOP ( expression )
    [ WITH TIES ]
]

Argumentos

expressão

A expressão numérica que especifica o número de linhas a serem retornadas. expressão é implicitamente convertida em um float valor se você especificar PERCENT. Caso contrário, expressão será convertida em bigint.

PERCENTAGEM

Indica que a consulta retorna apenas a primeira expressão porcentagem de linhas do conjunto de resultados. Os valores fracionários são arredondados para o próximo valor inteiro.

COM GRAVATAS

Retorna duas ou mais linhas que empatam em último lugar no conjunto de resultados limitado. Você deve usar esse argumento com a cláusula ORDER BY. WITH TIES pode fazer com que mais linhas sejam retornadas do que o valor especificado em expressão. Por exemplo, se expressão estiver definida como 5 mas mais duas linhas corresponderem aos valores das colunas ORDER BY na linha 5, o conjunto de resultados conterá sete linhas.

Você pode especificar a cláusula TOP com o argumento WITH TIES somente em SELECT instruções e somente se também especificar a cláusula ORDER BY. A ordem devolvida de subordinação dos registos é arbitrária. ORDER BY não afeta essa regra.

Melhores práticas

Em uma declaração SELECT, sempre use uma cláusula ORDER BY com a cláusula TOP. Esta é a única maneira de indicar de forma previsível quais linhas são afetadas por TOP.

Use OFFSET e FETCH na cláusula ORDER BY em vez da cláusula TOP para implementar uma solução de paginação de consulta. Uma solução de paginação (ou seja, enviar partes ou páginas de dados para o cliente) é mais fácil de implementar usando cláusulas OFFSET e FETCH. Para obter mais informações, consulte cláusula SELECT - ORDER BY.

Use TOP (ou OFFSET e FETCH) em vez de SET ROWCOUNT para limitar o número de linhas retornadas. Esses métodos são preferidos em relação ao uso de SET ROWCOUNT pelos seguintes motivos:

• Como parte de uma instrução SELECT, o otimizador de consulta pode considerar o valor de expressão nas cláusulas TOP ou FETCH durante a otimização da consulta. Como você usa SET ROWCOUNT fora de uma instrução que executa uma consulta, seu valor não pode ser considerado em um plano de consulta.

Suporte de compatibilidade

Para compatibilidade com versões anteriores, os parênteses são opcionais em SELECT instruções se a expressão for uma constante inteira. Recomendamos que você sempre use parênteses para TOP em SELECT declarações. Isso fornece consistência com seu uso necessário em declarações INSERT, UPDATE, MERGEe DELETE.

Interoperabilidade

A expressão TOP não afeta as instruções que podem ser executadas devido a um gatilho. As tabelas inserted e deleted nos gatilhos retornam apenas as linhas que são realmente afetadas pelas instruções INSERT, UPDATE, MERGEou DELETE. Por exemplo, se um INSERT TRIGGER é acionado como resultado de uma instrução INSERT que usou uma cláusula TOP.

O SQL Server permite a atualização de linhas por meio de modos de exibição. Como você pode incluir a cláusula TOP na definição de exibição, determinadas linhas podem desaparecer da exibição se as linhas não atenderem mais aos requisitos da expressão TOP devido a uma atualização.

Quando especificado na instrução MERGE, a cláusula TOP aplica-se depois de toda a tabela de origem e toda a tabela de destino forem unidas. Além disso, as linhas unidas que não se qualificam para uma ação de inserção, atualização ou exclusão são removidas. A cláusula TOP reduz ainda mais o número de linhas unidas para o valor especificado e as ações de inserção, atualização ou exclusão se aplicam às linhas unidas restantes de forma não ordenada. Ou seja, não há uma ordem na qual as linhas são distribuídas entre as ações definidas nas cláusulas WHEN. Por exemplo, se a especificação TOP (10) afetar 10 linhas, sete dessas linhas poderão ser atualizadas e três inseridas. Ou, um pode ser excluído, cinco atualizados, quatro inseridos, e assim por diante. Como a instrução MERGE faz uma verificação completa da tabela das tabelas de origem e de destino, o desempenho de E/S pode ser afetado quando você usa a cláusula TOP para modificar uma tabela grande criando vários lotes. Nesse cenário, é importante garantir que todos os lotes sucessivos tenham como destino novas linhas.

Tenha cuidado ao especificar a cláusula TOP em uma consulta que contém um operador UNION, UNION ALL, EXCEPTou INTERSECT. É possível escrever uma consulta que retorna resultados inesperados porque a ordem na qual as cláusulas TOP e ORDER BY são processadas logicamente nem sempre é intuitiva quando esses operadores são usados em uma operação selecionada. Por exemplo, dada a tabela e os dados a seguir, suponha que você deseja devolver o carro vermelho mais barato e o carro azul mais barato. Ou seja, o sedã vermelho e a van azul.

CREATE TABLE dbo.Cars
(
    Model VARCHAR (15),
    Price MONEY,
    Color VARCHAR (10)
);

INSERT dbo.Cars
VALUES ('sedan', 10000, 'red'),
    ('convertible', 15000, 'blue'),
    ('coupe', 20000, 'red'),
    ('van', 8000, 'blue');

Para obter esses resultados, você pode escrever a seguinte consulta.

SELECT TOP (1) Model, Color, Price
FROM dbo.Cars
WHERE Color = 'red'
UNION ALL
SELECT TOP (1) Model, Color, Price
FROM dbo.Cars
WHERE Color = 'blue'
ORDER BY Price ASC;
GO

Aqui está o conjunto de resultados.

 Model         Color      Price
 ------------- ---------- -------
 sedan         red        10000.00
 convertible   blue       15000.00

Os resultados inesperados são retornados porque a cláusula TOP é logicamente executada antes da cláusula ORDER BY, que classifica os resultados do operador (UNION ALL neste caso). Assim, a consulta anterior retorna qualquer carro vermelho e qualquer carro azul e, em seguida, ordena o resultado dessa união pelo preço. O exemplo a seguir mostra o método correto de escrever essa consulta para obter o resultado desejado.

SELECT Model, Color, Price
FROM (SELECT TOP (1) Model, Color, Price
      FROM dbo.Cars
      WHERE Color = 'red'
      ORDER BY Price ASC) AS a
UNION ALL
SELECT Model, Color, Price
FROM (SELECT TOP (1) Model, Color, Price
      FROM dbo.Cars
      WHERE Color = 'blue'
      ORDER BY Price ASC) AS b;
GO

Usando TOP e ORDER BY em uma operação de subseleção, você garante que os resultados da cláusula ORDER BY sejam aplicados à cláusula TOP e não à classificação do resultado da operação UNION.

Aqui está o conjunto de resultados.

 Model         Color      Price
 ------------- ---------- -------
 sedan         red        10000.00
 van           blue        8000.00

Limitações

Quando você usa TOP com INSERT, UPDATE, MERGEou DELETE, as linhas referenciadas não são organizadas em nenhuma ordem. Além disso, você não pode especificar diretamente a cláusula ORDER BY nessas declarações. Se você precisar usar TOP para inserir, excluir ou modificar linhas em uma ordem cronológica significativa, use TOP com uma cláusula ORDER BY especificada em uma instrução subselect. Consulte a seção Exemplos neste artigo.

Não é possível usar TOP em instruções UPDATE ou DELETE em modos de exibição particionados.

Não é possível combinar TOP com OFFSET e FETCH na mesma expressão de consulta (no mesmo escopo de consulta). Para obter mais informações, consulte cláusula SELECT - ORDER BY.

Exemplos

Os exemplos de código Transact-SQL neste artigo usam o banco de dados de exemplo ou , que você pode baixar da home page Microsoft SQL Server Samples and Community Projects.

Categoria	Elementos de sintaxe em destaque
Sintaxe básica	TOP * PERCENT
Incluindo valores de empate	WITH TIES
Limitar as linhas afetadas por DELETE, INSERT ou UPDATE	DELETE, INSERT, UPDATE

Sintaxe básica

Os exemplos nesta seção demonstram a funcionalidade básica da cláusula ORDER BY usando a sintaxe mínima necessária.

Um. Use TOP com um valor constante

Os exemplos a seguir usam um valor constante para especificar o número de funcionários retornados no conjunto de resultados da consulta. No primeiro exemplo, as primeiras 10 linhas indefinidas são retornadas porque uma cláusula ORDER BY não é usada. No segundo exemplo, uma cláusula ORDER BY é usada para devolver os 10 principais funcionários recém-contratados.

USE AdventureWorks2022;
GO

-- Select the first 10 random employees.
SELECT TOP (10) JobTitle, HireDate
FROM HumanResources.Employee;
GO

-- Select the first 10 employees hired most recently.
SELECT TOP (10) JobTitle, HireDate
FROM HumanResources.Employee
ORDER BY HireDate DESC;
GO

B. Usar TOP com uma variável

O exemplo a seguir usa uma variável para especificar o número de funcionários que são retornados no conjunto de resultados da consulta.

USE AdventureWorks2022;
GO

DECLARE @p AS INT = 10;

SELECT TOP (@p) JobTitle, HireDate, VacationHours
FROM HumanResources.Employee
ORDER BY VacationHours DESC;
GO

C. Especificar uma percentagem

O exemplo a seguir usa PERCENT para especificar o número de funcionários que são retornados no conjunto de resultados da consulta. São 290 funcionários na tabela HumanResources.Employee. Como cinco por cento de 290 é um valor fracionário, o valor é arredondado para o próximo número inteiro.

USE AdventureWorks2022;
GO

SELECT TOP (5) PERCENT JobTitle, HireDate
FROM HumanResources.Employee
ORDER BY HireDate DESC;
GO

Incluir valores de empate

Um. Use WITH TIES para incluir linhas que correspondam aos valores na última linha

O exemplo a seguir obtém os 10% mais altos de todos os funcionários com o salário mais alto e os devolve em ordem decrescente de acordo com seu salário. Especificar WITH TIES garante que os funcionários com salários iguais ao menor salário devolvido (a última linha) também sejam incluídos no conjunto de resultados, mesmo que exceda 10% dos funcionários.

USE AdventureWorks2022;
GO

SELECT TOP (10) PERCENT WITH TIES pp.FirstName,
                                  pp.LastName,
                                  e.JobTitle,
                                  e.Gender,
                                  r.Rate
FROM Person.Person AS pp
     INNER JOIN HumanResources.Employee AS e
         ON pp.BusinessEntityID = e.BusinessEntityID
     INNER JOIN HumanResources.EmployeePayHistory AS r
         ON r.BusinessEntityID = e.BusinessEntityID
ORDER BY Rate DESC;
GO

Limitar as linhas afetadas por DELETE, INSERT ou UPDATE

Um. Use TOP para limitar o número de linhas excluídas

Quando você usa uma cláusula TOP (<n>) com DELETE, a operação de exclusão é feita em uma seleção indefinida de n número de linhas. Ou seja, a instrução DELETE escolhe qualquer (n) número de linhas que atendam aos critérios definidos na cláusula WHERE. O exemplo a seguir exclui 20 linhas da tabela PurchaseOrderDetail que tenham datas de vencimento anteriores a 1º de julho de 2002.

USE AdventureWorks2022;
GO

DELETE TOP (20)
FROM Purchasing.PurchaseOrderDetail
WHERE DueDate < '20020701';
GO

Se você quiser usar TOP para excluir linhas em uma ordem cronológica significativa, use TOP com ORDER BY em uma instrução subselect. A consulta a seguir exclui as 10 linhas da tabela PurchaseOrderDetail que têm as datas de vencimento mais antigas. Para garantir que apenas 10 linhas sejam excluídas, a coluna especificada na instrução subselect (PurchaseOrderID) é a chave primária da tabela. O uso de uma coluna não-chave na instrução subselect pode resultar na exclusão de mais de 10 linhas se a coluna especificada contiver valores duplicados.

USE AdventureWorks2022;
GO

DELETE Purchasing.PurchaseOrderDetail
WHERE PurchaseOrderDetailID IN (
    SELECT TOP 10 PurchaseOrderDetailID
    FROM Purchasing.PurchaseOrderDetail
    ORDER BY DueDate ASC
);
GO

B. Use TOP para limitar o número de linhas inseridas

O exemplo a seguir cria a tabela EmployeeSales e insere o nome e os dados de vendas do ano até a data para os cinco principais funcionários da tabela HumanResources.Employee. A instrução INSERT escolhe quaisquer cinco linhas retornadas pela instrução SELECT que atendam aos critérios definidos na cláusula WHERE. A cláusula OUTPUT exibe as linhas inseridas na tabela EmployeeSales. A cláusula ORDER BY na declaração SELECT não é usada para determinar os cinco principais funcionários.

USE AdventureWorks2022;
GO

IF OBJECT_ID('dbo.EmployeeSales', 'U') IS NOT NULL
    DROP TABLE dbo.EmployeeSales;
GO

CREATE TABLE dbo.EmployeeSales
(
    EmployeeID NVARCHAR (11) NOT NULL,
    LastName NVARCHAR (20) NOT NULL,
    FirstName NVARCHAR (20) NOT NULL,
    YearlySales MONEY NOT NULL
);
GO

INSERT TOP (5) INTO dbo.EmployeeSales
OUTPUT
    inserted.EmployeeID,
    inserted.FirstName,
    inserted.LastName,
    inserted.YearlySales
SELECT sp.BusinessEntityID,
       c.LastName,
       c.FirstName,
       sp.SalesYTD
FROM Sales.SalesPerson AS sp
     INNER JOIN Person.Person AS c
         ON sp.BusinessEntityID = c.BusinessEntityID
WHERE sp.SalesYTD > 250000.00
ORDER BY sp.SalesYTD DESC;
GO

Se você quiser usar TOP para inserir linhas em uma ordem cronológica significativa, use TOP com ORDER BY em uma instrução subselect. O exemplo a seguir mostra como fazer isso. A cláusula OUTPUT exibe as linhas inseridas na tabela EmployeeSales. Os cinco principais funcionários agora são inseridos com base nos resultados da cláusula ORDER BY em vez de linhas indefinidas.

INSERT INTO dbo.EmployeeSales
OUTPUT
    inserted.EmployeeID,
    inserted.FirstName,
    inserted.LastName,
    inserted.YearlySales
SELECT TOP (5) sp.BusinessEntityID,
               c.LastName,
               c.FirstName,
               sp.SalesYTD
FROM Sales.SalesPerson AS sp
     INNER JOIN Person.Person AS c
         ON sp.BusinessEntityID = c.BusinessEntityID
WHERE sp.SalesYTD > 250000.00
ORDER BY sp.SalesYTD DESC;
GO

C. Use TOP para limitar o número de linhas atualizadas

O exemplo a seguir usa a cláusula TOP para atualizar linhas em uma tabela. Quando você usa uma cláusula TOP (<n>) com UPDATE, a operação de atualização é executada em um número indefinido de linhas. Ou seja, a instrução UPDATE escolhe qualquer (n) número de linhas que atendam aos critérios definidos na cláusula WHERE. O exemplo a seguir atribui 10 clientes de um vendedor para outro.

USE AdventureWorks2022;

UPDATE TOP (10)
Sales.Store
SET SalesPersonID = 276
WHERE SalesPersonID = 275;
GO

Se você tiver que usar TOP para aplicar atualizações em uma cronologia significativa, deverá usáTOP juntamente com ORDER BY em uma instrução subselect. O exemplo a seguir atualiza as horas de férias dos 10 funcionários com as primeiras datas de contratação.

UPDATE HumanResources.Employee
SET VacationHours = VacationHours + 8
FROM (SELECT TOP 10 BusinessEntityID
      FROM HumanResources.Employee
      ORDER BY HireDate ASC) AS th
WHERE HumanResources.Employee.BusinessEntityID = th.BusinessEntityID;
GO

Exemplos: Azure Synapse Analytics and Analytics Platform System (PDW)

O exemplo a seguir retorna as 31 principais linhas que correspondem aos critérios de consulta. A cláusula ORDER BY garante que as 31 linhas retornadas sejam as primeiras 31 linhas com base em uma ordem alfabética da coluna LastName.

Usando TOP sem especificar vínculos.

SELECT TOP (31) FirstName, LastName
FROM DimEmployee
ORDER BY LastName;

Resultado: 31 linhas são retornadas.

Usando TOP, especificando WITH TIES.

SELECT TOP (31) WITH TIES FirstName, LastName
FROM DimEmployee
ORDER BY LastName;

Resultado: 33 linhas são devolvidas, porque três funcionários nomeados Brown empate para a 31ª fila.

Conteúdo relacionado

• SELECIONAR (Transact-SQL)
• INSERIR (Transact-SQL)
• UPDATE (Transact-SQL)
• DELETE (Transact-SQL)
• SELECT - ORDER BY cláusula (Transact-SQL)
• SET ROWCOUNT (Transact-SQL)
• MERGE (Transact-SQL)