Transact-SQL: T-SQL e a cláusula TOP

O Transact-SQL (Transact-Structure Query Language) � uma extens�o para a linguagem de programa��o de banco de dados SQL. Uma linguagem poderosa que oferece muitas caracter�sticas, al�m de uma grande variedade de tipos de dados, objetos tempor�rios, controle de transa��es, exce��o e tratamento de erros, dentre outros recursos.

Trabalhando com a cl�usula TOP

A cl�usula TOP permite controlar o n�mero de linhas a serem devolvidas ou que s�o afetadas por uma consulta. Percebemos melhor a utiliza��o dessa cl�usula quando desejamos retornar um subconjunto de linhas de um conjunto de resultados. A cl�usula TOP nos permite uma maneira f�cil de satisfazer a esta necessidade. Alguns dos exemplos que podemos citar para a utiliza��o dessa cl�usula s�o quando:

Queremos retornar apenas um subconjunto de registros para validar nossos c�digos ou;
Quando precisamos determinar que pelo menos uma linha atenda a uma condi��o WHERE especial.

Para que possamos explicar como esta cl�usula funciona, deixe-nos dar-lhe a sintaxe b�sica e alguns exemplos. Desta forma, ser� mais f�cil para entendermos e vermos as diferentes nuan�as de se utilizar a cl�usula TOP que podem afetar o que � retornado das nossas consultas.

Sintaxe da cl�usula TOP

A sintaxe para a cl�usula TOP � relativamente simples, como apresentada pela Listagem 1. Podemos usar a cl�usula TOP colocando esta sintaxe em qualquer instru��o SELECT, DELETE, INSERT ou UPDATE.

Listagem 1. Sintaxe da cl�usula TOP.

TOP (expression) [PERCENT]
      [WITH TIES]

O valor de "expression" � um valor num�rico. Este valor num�rico ser� convertido para um tipo de dados de ponto flutuante se a op��o PERCENT for usada, ou de um tipo de dados BIGINT se a op��o PERCENT n�o for utilizada. O valor de "expression" pode ser representado como um n�mero ou pode ser especificado como uma vari�vel local.

A op��o PERCENT, quando especificada, identifica que o SQL Server retornar� uma porcentagem de linhas do conjunto de resultados com base no n�mero representado pelo valor "expression". Quando a op��o PERCENT for omitida, o SQL Server ir� retornar o n�mero de linhas representadas pelo valor "expression".

A op��o WITH TIES, que foi introduzida na vers�o 2005 do SQL Server, � usada para dizer ao SQL Server para retornar todas as linhas que t�m os mesmos valores para o ORDER BY colunas como a �ltima linha. Ao usar a op��o WITH TIES, pode ser que o SQL Server retorne mais linhas do que o especificado pelo valor da "expression". A op��o WITH TIES s� � v�lida para instru��es SELECT que contenham uma cl�usula ORDER BY.

Criando um exemplo b�sico

Antes que possamos mostrar um exemplo das diferentes formas de usarmos a cl�usula TOP, ser� necess�rio criarmos primeiramente uma tabela de exemplo e ent�o inserir alguns dados. Na Listagem 2 criamos uma tabela, a qual chamaremos de dbo.DevmediaVendas para ser usada em todos os exemplos utilizados aqui.

Listagem 2. Criando a tabela dbo.DevmediaVendas.

SET NOCOUNT ON;
      USE tempdb;
      CREATE TABLE dbo.DevmediaVendas ( 
                      AgenteVendas varchar(30), 
                      Regiao varchar(10), 
                      AcumuladoVendas decimal(10,2));
      INSERT INTO dbo.DevmediaVendas VALUES 
          ('Jo�o Vasconcelos', 'Oeste', 78931.01),
          ('Maria Jo�o', 'Oeste', 862341.63),
          ('Mariana Correia', 'Oeste', 20001121.67),
          ('Martin Am�lio', 'Oeste', 120845.80),
          ('Edson Dionisio', 'Leste', 12008500.60), 
          ('Olga Meyer', 'Oeste', 519021.48),
          ('Samuel Guerreiro', 'Leste', 862341.63);

Nossa tabela exemplo cont�m informa��es de vendas de uma empresa fict�cia chamada Devmedia. A Companhia Devmedia possui resid�ncias para vendas em duas regi�es: Leste e Oeste. Cada regi�o tem cinco agentes de vendas. Na Listagem 2 que criamos, temos informa��es de AcumuladoVendas (valor total das vendas) para cada agente e em cada regi�o.

Exemplo simples da cl�usula TOP

Para o nosso primeiro exemplo, temos a exig�ncia de encontrar a parte superior dos dois Agentes de Vendas da Companhia com base no valor acumulativo de suas vendas. O c�digo apresentado na Listagem 3 cont�m a solu��o com a cl�usula TOP.

Listagem 3. Encontrando os dois agentes com maior ac�mulo de vendas

USE tempdb;
      GO
      SELECT TOP(2) AgenteVendas, Regiao, AcumuladoVendas
      FROM dbo.DevmediaVendas
      ORDER BY AcumuladoVendas DESC;

No exemplo da Listagem 3 inclu�mos a cl�usula ORDER BY, pois ela se faz necess�rio para garantir que a cl�usula TOP selecione o Agente de vendas que possua o maior valor acumulado de vendas. Quando usamos a cl�usula TOP sem a cl�usula ORDER BY, o SQL Server retorna um conjunto aleat�rio de informa��es. Para um teste simples, removam a cl�usula ORDER BY e executem novamente a consulta da Listagem 3 para ver quais linhas aleat�rias ser�o devolvidas.

Exemplo Usando a op��o PERCENT da cl�usula TOP

Se quisermos retornar um percentual dos principais registros em um conjunto, ent�o precisaremos utilizar a cl�usula TOP com a op��o PERCENT. Vejamos no c�digo da Listagem 4 como ser� a visualiza��o de um percentual de 50%.

Listagem 4. Retornando o Top 50% das linhas


      USE tempdb;
      GO
      SELECT TOP(50) PERCENT AgenteVendas, Regiao, AcumuladoVendas
      FROM dbo.DevmediaVendas
      ORDER BY AcumuladoVendas DESC;

Usando uma vari�vel para controlar a cl�usula TOP

H� momentos em que n�o sabemos com anteced�ncia o n�mero de linhas que desejamos retornar. Se este for o caso, podemos usar uma vari�vel para controlar a identifica��o do n�mero de linhas que ser�o retornadas. Este exemplo ser� de acordo com o exposto pela Listagem 5.

Listagem 5. Usando uma vari�vel para identificar o n�mero de linhas para retornar

USE tempdb;
      GO
      DECLARE @Number INT = 2;
      SELECT TOP(@Number) AgenteVendas, Regiao, AcumuladoVendas
      FROM dbo.DevmediaVendas
      ORDER BY AcumuladoVendas DESC;
       
      SET @Number = 50;
      SELECT TOP(@Number) PERCENT AgenteVendas, Regiao, AcumuladoVendas
      FROM dbo.DevmediaVendas
      ORDER BY AcumuladoVendas DESC;

No exemplo apresentado na Listagem 5 declaramos uma vari�vel chamada @Number para controlar o n�mero de linhas retornadas a partir das duas consultas SELECT distintas. Na primeira instru��o SELECT que definimos, a vari�vel @Number � 2. Definimos, ent�o, a vari�vel @Number na segunda instru��o SELECT para 50 para que ele retorne os mesmos resultados que est�o presentes na Figura 1.

resultado das consultas com @Number

Figura 1. Resultado das consultas com @Number

Usando a op��o WITH TIES

Para nos certificarmos de que nossa consulta TOP sempre retorne todas as linhas que t�m valores de colunas que s�o iguais para a �ltima linha, devemos ent�o incluir a op��o WITH TIES (�Com la�os�). Ao usar esta op��o, � poss�vel trazer de volta mais linhas do que o n�mero que especificarmos com a cl�usula TOP. Vejamos, de acordo com a Listagem 6, o resultado obtido com essa op��o.

Listagem 6. Usando a op��o WITH TIES

USE tempdb;
      GO
      SELECT TOP(2) WITH TIES AgenteVendas, Regiao, AcumuladoVendas
      FROM dbo.DevmediaVendas
      ORDER BY AcumuladoVendas DESC;

Usando a cl�usula TOP com uma instru��o UPDATE

Podemos limitar o n�mero de linhas afetadas por uma instru��o UPDATE usando a cl�usula TOP. O c�digo apresentado na Listagem 7 atualizar� duas linhas aleat�rias na nossa tabela DevmediaVendas.

Listagem 7. UPDATE com a cl�usula TOP sem ordenar dados

USE tempdb;
      GO
      -- Registros antes do UPDATE
      SELECT * FROM dbo.DevmediaVendas
      WHERE Regiao = 'Oeste';
      -- Update usando a cl�usula TOP
      UPDATE TOP (2) dbo.DevmediaVendas
      SET AcumuladoVendas = 100000.00
      FROM dbo.DevmediaVendas
      WHERE Regiao = 'Oeste'
      -- Registros ap�s Update
      SELECT * FROM dbo.DevmediaVendas
      WHERE Regiao = 'Oeste';

Ao analisar o c�digo da Listagem 7 podemos ver que s�o exibidos os registros na tabela dbo.DevmediaVendas antes e depois da instru��o de atualiza��o. Os resultados com base nessa atualiza��o est�o sendo exibidos na Figura 2.

Registros antes e depois do update

Figura 2. Registros antes e depois do update.

Ao analisar os resultados da Listagem 7, podemos observar que a instru��o UPDATE atualizou o valor AcumuladoVendas para Jo�o Vasconcelos e Maria Jo�o. Se compararmos as linhas atualizadas para suas linhas originais antes de serem atualizadas, podemos ver que o valor AgenteVendas, que teve o maior e o menor AcumuladoVendas na regi�o Oeste, foram os que foram atualizados. Este n�o � o resultado que quer�amos! A raz�o pela qual isso aconteceu � porque a nossa declara��o UDPATE atualizou aleatoriamente a nossa tabela para os registros que tiveram um valor para a regi�o Oeste.

Desde que o que realmente queremos seja restringir o n�mero de instru��es da atualiza��o usando a cl�usula TOP e queiramos ter certeza de que atualizaremos os registros com base no AcumuladoVendas, precisamos escrever nosso c�digo de forma diferente, de acordo com o que fizemos na Listagem 8.

Listagem 8. UPDATE com a cl�usula TOP dos dados.

USE tempdb;
      GO
      UPDATE dbo.DevmediaVendas  
      SET AcumuladoVendas = 6666666.00
      FROM 
      (SELECT TOP(2) AgenteVendas FROM dbo.DevmediaVendas
       WHERE Regiao = 'Oeste'
       ORDER BY AcumuladoVendas DESC) TS
      WHERE dbo.DevmediaVendas.AgenteVendas = TS.AgenteVendas
      -- Records after Update
      SELECT * FROM dbo.DevmediaVendas
      WHERE Regiao = 'Oeste';

Ao analisarmos a sa�da, de acordo com a Figura 3, e compararmos os valores da coluna para AgenteVendas Mariana Correia e Olga Meyer, com os valores apresentados na Figura 2, para o mesmo valor AgenteVendas, veremos que esses dois valores AgenteVendas tem o top de vendas para a regi�o Oeste. A consulta na Listagem 8 conseguiu isso atrav�s da cria��o de uma sub-consulta que continha os dois principais valores AgenteVendass, que foram representados pelo alias (�apelido�) TS. Os valores AgenteVendas retornados por essa subconsulta foram ent�o usados na cl�usula WHERE para restringir a instru��o UPDATE, a fim de que apenas esses dois valores AgenteVendas tivessem o AcumuladoVendas atualizado para 6.666.666,00.

Update com a cl�usula TOP

Figura 3. Update com a cl�usula TOP.

Usando a cl�usula TOP com uma instru��o INSERT

Haver� momentos em que desejaremos inserir o subconjunto de linhas do resultado de uma consulta em uma tabela. Isto pode ser conseguido usando a cl�usula TOP em conjunto com um INSERT. Cuidados devem ser tomados nos casos onde colocamos esta cl�usula, caso contr�rio, n�o ser� poss�vel � inser��o dos registros onde desejamos.

Para o nosso exemplo, queremos inserir os dois valores principais AgenteVendas e AcumuladoVendas em uma tabela chamada dbo.TopVendas. A Listagem 9 tem a nossa primeira tentativa em satisfazer as nossas necessidades.

Listagem 9. Cl�usula TOP na instru��o INSERT

USE tempdb;
      GO
      CREATE TABLE dbo.TopVendas ( 
                      AgenteVendas varchar(30), 
                      Regiao varchar(10), 
                      AcumuladoVendas decimal(10,2));
      INSERT TOP(2) INTO dbo.TopVendas
      SELECT * FROM dbo.DevmediaVendas
      ORDER BY AcumuladoVendas DESC;
      SELECT * FROM dbo.TopVendas;

Na Listagem 9 vemos que n�o foram atendidos exatamente os requisitos referidos acima. Ao analisarmos a sa�da produzida a partir desta consulta, podemos observar que n�o foram inseridos os dois melhores valores de AcumuladoVendas. Isto porque, quando colocamos a cl�usula TOP, mesmo ao lado da cl�usula INSERT, ele disse ao SQL Server para inserir aleatoriamente duas linhas a partir dos resultados da subconsulta SELECT. Para inserirmos corretamente os dois primeiros valores AcumuladoVendas, precisamos escrever uma subconsulta SELECT para retornar apenas as duas linhas que queremos inserir, como fizemos na Listagem 10.

Listagem 10. Inserindo dados corretamente na tabela Two AgenteVendas com Top

USE tempdb;
      GO
      DROP TABLE dbo.TopVendas;
      CREATE TABLE dbo.TopVendas ( 
                      AgenteVendas varchar(30), 
                      Regiao varchar(10), 
                      AcumuladoVendas decimal(10,2));
      INSERT INTO dbo.TopVendas
      SELECT TOP(2) * FROM dbo.DevmediaVendas
      ORDER BY AcumuladoVendas DESC;
      SELECT * FROM dbo.TopVendas;

Ao analisarmos a sa�da encontrada na Figura 4, que foi produzida pela instru��o SELECT final da Listagem 10, podemos ver que esta instru��o INSERT colocou as duas linhas de forma correta na tabela dbo.TopVendas.

Inser��o dos Tops da venda na tabela auxiliar

Figura 4. Inser��o dos Tops da venda na tabela auxiliar.

Usando a cl�usula TOP com uma instru��o DELETE

Como dito anteriormente, podemos usar a cl�usula TOP tamb�m em instru��es do tipo DELETE. Claro que alguns cuidados devem ser tomados quando tratamos dessa instru��o, j� que ela pode excluir registros que n�o gostar�amos. Se realmente desejarmos excluir linhas aleat�rias, ent�o podemos escrever uma cl�usula TOP, como feita na Listagem 11.

Listagem 11. C�digo para excluir aleatoriamente duas fileiras

USE tempdb;
      GO
      BEGIN TRANSACTION;
      SELECT * FROM dbo.DevmediaVendas;
      DELETE TOP (2) FROM dbo.DevmediaVendas
      WHERE AcumuladoVendas < 6666667.00;
      SELECT * FROM dbo.DevmediaVendas;
      ROLLBACK;

Observem que usamos neste caso uma instru��o ROLLBACK na listagem 11, assim, nenhuma linha foi realmente exclu�da da tabela de exemplo. Caso queiramos realmente excluir as duas linhas que tenham o menor valor em AcumuladoVendas, precisar�amos usar uma subconsulta para selecionar um valor de chave �nica que iria identificar as linhas que continham os dois valores mais baixos dos totais de vendas. Assim, temos o exemplo feito na Listagem 12.

Listagem 12. Excluindo dados da tabela DevmediaVendas com TOP.

USE tempdb;
      GO
      BEGIN TRANSACTION;
      DELETE FROM dbo.DevmediaVendas
      WHERE AgenteVendas in (SELECT TOP(2) AgenteVendas FROM dbo.DevmediaVendas
                           ORDER by AcumuladoVendas ASC);
      SELECT * FROM dbo.DevmediaVendas;
      ROLLBACK;

Desta forma, onde ocorrerem os dois valores AgenteVendas que contenham os valores mais baixos associados a AcumuladoVendas, eles ser�o apagados. Se quisermos remover tamb�m todos os registros que tenham o mesmo valor que o �ltimo registro identificado pela cl�usula TOP, precisaremos adicionar a op��o WITH TIES. Agora ao executarmos o c�digo da Listagem 13, teremos tamb�m exclu�do o registro dbo.DevmediaVendas de "Jo�o Vasconcelos", al�m do "Jason Ramos" e "Maria Jo�o".

Listagem 13. Corretamente Inserindo tabela em Top Two AgenteVendas

DELETE FROM dbo.DevmediaVendas
      WHERE AgenteVendas in (SELECT TOP(2) WITH TIES AgenteVendas FROM dbo.DevmediaVendas
                           ORDER by AcumuladoVendas ASC);
      SELECT * FROM dbo.DevmediaVendas;

Depois de executarmos este c�digo, podemos usar a instru��o SELECT para mostrar que ambas as linhas que tiveram um AcumuladoVendas abaixo de 1000000.00 foram exclu�das.

Cuidados ao usar a cl�usula TOP com UNION, EXCEPT e INTERSECT

Agora, indo um pouco mais al�m, precisamos ser cuidadosos ao utilizar a cl�usula TOP quando se trata de grava��es de consultas com tipos UNION, UNION ALL, INTERSECT ou EXCEPT. Se suas consultas individuais n�o cont�m a instru��o ORDER BY, elas poder�o n�o obter os resultados esperados. Para esta demonstra��o estaremos usando o c�digo da Listagem 14 para criar os dados de teste.

Listagem 14. Cria��o da tabela Vendas.

USE tempdb;
      CREATE TABLE dbo.Vendas ( 
                      NomeAgente varchar(30), 
                      Regiao varchar(10), 
                      AcumuladoVendas decimal(10,2));
      INSERT INTO dbo. Vendas VALUES 
          ('Jo�o Vasconcelos', 'Oeste', 1100000.00),
          ('Maria Jo�o', 'Oeste', 2453252.90),
          ('Mariana Correia', 'Oeste', 99101.45),
          ('Samuel Guerreiro', 'Leste', 862341.63),
          ('Nicolas Tavares', 'Leste', 983422.87),
          ('Jason Ramos', 'Leste', 135424.51);

Na tabela criada na Listagem 14 temos um conjunto de registros de vendas que seguem o valor da quantidade total de vendas para v�rios agentes de vendas. Queremos ent�o escrever uma consulta que retorne o agente de vendas que mais vendeu em cada regi�o. A fim de fazer isso, vamos usar a cl�usula TOP, a cl�usula WHERE e o operador UNION. Para demonstrar como a cl�usula TOP em uma instru��o UNION pode n�o retornar os resultados esperados, executaremos o c�digo apresentado na Listagem 15.

Listagem 15. Cl�usula TOP e os retornos imprevis�veis.

USE tempdb;
      GO
      SELECT TOP(1) NomeAgente, Regiao, AcumuladoVendas 
                      FROM dbo.Vendas
                      WHERE Regiao = 'Leste'
      UNION
      SELECT TOP(1) NomeAgente, Regiao, AcumuladoVendas
                      FROM dbo.Vendas
                      WHERE Regiao = 'Oeste'
      ORDER BY AcumuladoVendas DESC;

Melhores Pr�ticas para trabalhar com a cl�usula TOP

Ao utilizarmos a cl�usula TOP, devemos considerar alguns pontos importantes, que s�o:

A fim de garantir resultados consistentes, sempre usar uma cl�usula ORDER BY quando se usa uma cl�usula TOP. Isso far� com que suas pesquisas retornem corretamente as linhas superiores de um conjunto ordenado de dados. Se n�o usarmos a cl�usula ORDER BY, o SQL Server retornar� um conjunto aleat�rio de linhas. Isso ocorre porque um conjunto de dados produzido sem a cl�usula ORDER BY n�o tem fim.
N�o usem a cl�usula TOP para executar uma fun��o de pagina��o ou de janelas para a sua aplica��o. � mais f�cil implementar uma fun��o de janelas ou pagina��o usando as op��es de offset e FETCH da cl�usula ORDER BY.
Certifiquem-se de que ser� usada uma cl�usula ORDER BY em cada instru��o individual de SELECT ao usar TOP com operadores UNION, UNION ALL, INTERSECT e EXCEPT. Se n�o fizermos isso, ent�o nossas instru��es SELECT podem retornar linhas aleat�rias que nos dar�o resultados diferentes do que os esperados.

Ent�o � isso pessoal, nesse artigo apresentamos uma maneira de como trabalharmos com a cl�usula TOP em nossos projetos para que, dessa forma, n�o tenhamos problemas futuros em nossas aplica��es. Nos vemos na pr�xima, at� mais!

Confira outros conte�dos:

SQL SUM: somando os valores de uma...

SQL: INNER JOIN

SQL: Introdu��o ao Where

Assista grátis a nossa aula inaugural

Perguntas frequentes

Quem somos?

Por que a programação se tornou a profissão mais promissora da atualidade?

Como faço para começar a estudar?

Em quanto tempo de estudo vou me tornar um programador?

Sim, você pode se tornar um programador e não precisa ter diploma de curso superior!

O que eu irei aprender estudando pela DevMedia?

Principais diferenciais da DevMedia

Qual o investimento financeiro que preciso fazer para me tornar um programador?

Como funciona a forma de pagamento da DevMedia?

Por Edson Em 2014

Nossos casos de sucesso

Leonardo Carlos

Eu sabia pouqu�ssimas coisas de programa��o antes de come�ar a estudar com voc�s, fui me especializando em v�rias �reas e ferramentas que tinham na plataforma, e com essa bagagem consegui um est�gio logo no in�cio do meu primeiro per�odo na faculdade.

Lucas Rodrigues

Estudo aqui na Dev desde o meio do ano passado! Nesse per�odo a Dev me ajudou a crescer muito aqui no trampo.
Fui o primeiro desenvolvedor contratado pela minha empresa. Hoje eu lidero um time de desenvolvimento!
Minha meta � continuar estudando e praticando para ser um Full-Stack Dev!

Her�clito J�nior

Economizei 3 meses para assinar a plataforma e sendo sincero valeu muito a pena, pois a plataforma � bem intuitiva e muuuuito did�tica a metodologia de ensino. Sinto que estou EVOLUINDO a cada dia. Muito obrigado!

Julio Cablen

Nossa! Plataforma maravilhosa. To amando o curso de desenvolvimento front-end, tinha coisas que eu ainda n�o tinha visto. A did�tica � do jeito que qualquer pessoa consegue aprender. S�rio, to apaixonado, adorando demais.

Joelberth Sena

Adquiri o curso de voc�s e logo percebi que s�o os melhores do Brasil. � um passo a passo incr�vel. S� n�o aprende quem n�o quer. Foi o melhor investimento da minha vida!

Felipe Nunes

Foi um dos melhores investimentos que j� fiz na vida e tenho aprendido bastante com a plataforma. Voc�s est�o fazendo parte da minha jornada nesse mundo da programa��o, irei assinar meu contrato como programador gra�as a plataforma.

Wanderson Oliveira

Comprei a assinatura tem uma semana, aprendi mais do que 4 meses estudando outros cursos. Exerc�cios pr�ticos que n�o tem como n�o aprender, est�o de parab�ns!

Jos� Lucas

Obrigado DevMedia, nunca presenciei uma plataforma de ensino t�o presente na vida acad�mica de seus alunos, parab�ns!

Eduardo Dorneles

Aprendi React na plataforma da DevMedia h� cerca de 1 ano e meio... Hoje estou h� 1 ano empregado trabalhando 100% com React!

Adauto Junior

J� fiz alguns cursos na �rea e nenhum � t�o bom quanto o de voc�s. Estou aprendendo muito, muito obrigado por existirem. Est�o de parab�ns... Espero um dia conseguir um emprego na �rea.

Ver todos os casos de sucesso

Transact-SQL: T-SQL e a cl�usula TOP

Neste artigo apresentaremos o T-SQL(Transact-SQL) de uma forma um pouco diferente, pois vamos abordar os pontos mais avan�ados dessa extens�o do SQL. Neste artigo vamos trabalhar com a cl�usula TOP.