Component: Query

O componente Query é o método preferido para acessar dados em bancos de dados cliente/servidor. As seções a seguir descrevem as principais propriedades e métodos da classe TQuery.

Dica: O componente Query não possui uma propriedade TableName, como acontece com Table. Isso significa que, durante o projeto, você não poderá ver imediatamente uma lista de tabelas para o banco de dados atual. Para ver uma lista de tabelas, você poderá realizar uma de duas tarefas. Primeiro, você pode soltar temporariamente um componente Table no formulário, definir a propriedade DatabaseName e então ver a lista das tabelas na propriedade TableName. Você também pode selecionar o componente Query no formulário, dar um clique nele com o botão direito e depois escolher Explore no menu de contexto. Isso o levará ao SQL Explorer (versão Cliente/Server) ou ao BDE Administrator (versões Standard e Professional). Você pode usar qualquer uma dessas ferramentas para ver as tabelas de um banco de dados.

A propriedade SQL
A propriedade SQL é uma TStringList que contém as instruções SQL a serem executadas. Você pode definir o valor da propriedade SQL por meio do Object Inspector durante o projeto ou por meio do código durante a execução.
Para definir o valor durante o projeto, dê um clique no botão de reticências ao lado da propriedade SQL do Object Inspector. A caixa de diálogo String List Editor aparece, e você pode digitar em uma ou mais linhas de instruções SQL.

Dica: Lembre-se de que a caixa de diálogo String List Editor possui um recurso que lhe permite editar listas de strings no Code Editor do Delphi.

Ao incluir linhas na propriedade SQL durante a execução, certifique-se de que você apagará o conteúdo anterior - por exemplo:

• Query1.SQL.Clear;
• Query1.SQL.Add('select * from country');

É fácil pensar na propriedade SLQ como um string ao invés de uma lista de string. Se você não apagar a propriedade SQL antes de incluir um string, instruções SQL anteriores ainda estarão na lista de strings. Os erros quase certamente ocorrerão quando você tentar executar a instrução SQL.

Execução de instruções SQL
As instruções na propriedade SQL serão executadas quando o método Open ou o método ExecSQL for chamado. Se você estiver usando instruções SQL que incluem SELECT, use o método Open para executar a consulta SQL. Se estiver usando INSERT, UPDATE ou DELETE, você precisará usar o método ExecSQL para executar a consulta. O exemplo a seguir define a propriedade SQL e depois chama o método Open:

• Query1.SQL.Clear;
• Query1.SQL.Add('select * from country');
• Query1.Open;

A instrução SQL SELECT recupera certas colunas de um banco de dados. O asterisco diz ao servidor de banco de dados para retornar todas as colunas de uma tabela. O exemplo anterior, portanto, retorna a tabela inteira chamada country do banco de dados atual. Para retornar colunas específicas, use um código como este:

• Query1.SQL.Clear;
• Query1.SQL.Add('select Name, Capital from country');
• Query1.Open;

Nota: A definição da propriedade Active como True é o mesmo que chamar o método Open.

A instrução SQL DELETE exclui registros de um dataset. Para excluir um registro de um dataset, você pode usar um código como este:

• Query1.SQL.Clear;
• Query1.SQL.Add('delete from country where name = 'Royland');
• Query1.ExecSQL;

Observe que o método ExecSQL é usado no lugar do método Open. Como já disse, você precisa usar o método ExecSQL para executar uma consulta contendo instruções INSERT, UPDATE ou DELETE.
O comando INSERT insere um registro em um dataset:

• Query1.SQL.Add('insert into country');
• Query1.SQL.Add('(Name, Capital)');
• Query1.SQL.Add('values ("Royland", "Royville")');
• Query1.ExecSQL;

Nota: Observe o uso de aspas duplas no exemplo anterior. A sintaxe da SQL não deve ser confundida com a sintaxe do Object Pascal. A SQL permite o uso de aspas duplas ou apóstrofos em torno de nomes de valor. Você pode usar qualquer um, mas se usar apóstrofos dentro de um string, terá de usar aspas para delimitar o string. Qualquer um dos seguintes é válido:

• Query1.SQL.Add('values ("Royland", "Royville")');
• Query1.SQL.Add('values (' 'Royland' ', ''Royville' ')');

A atualização de um dataset usando o comando UPDATE se parece com isto:

• Query1.SQL.Clear;
• Query1.SQL.Add('update country');
• Query1.SQL.Add('set Capital = ''Royburg''');
• Query1.SQL.Add('where Name = "Royland"');
• Query1.ExecSQL;

Embora não seja minha intenção ensinar SQL, creio que alguns exemplos o ajudaram a iniciar.

Uso de parâmetros em instruções SQL
Instruções SQL usam parâmetros para que tenham mais flexibilidade. Um parâmetro em uma instrução SQL é semelhante a uma variável do Object Pascal. Um parâmetro em uma instrução SQL é precedido por dois-pontos. Considere, por exemplo, a seguinte instrução SQL:

• select * from country where name = :Param1

O parâmetro da instrução anterior se chama Param1. Quando esta instrução SQL é executada, o valor de Param1 na propriedade Params é substituído pelo nome do parâmetro:

• Query1.SQL.Add('select * from where Name = :Param1');
• Query1.ParamByName('Param1').AsString := 'Brasil';
• Query1.Open;

Você pode definir os valores de parâmetro da propriedade Params durante o projeto por meio da caixa de diálogo Parameters, mas na maioria das vezes você estará mudando os parâmetros durante a execução (que, logicamente, é a finalidade do uso do parâmetro). Observe no código anterior que o método ParamByName é usado para definir o valor de Param1. Este provavelmente é o modo mais fácil de se definir o valor do parâmetro. No entanto, existe outra maneira:

• Query1.Params[0].AsString := 'Brasil';

Aqui, a propriedade Items da classe TParam é usada para se definir o valor do parâmetro. O acesso a um parâmetro pelo índice pode causar mais erros do que o acesso do parâmetro pelo nome, pois você precisa se lembrar das ordens de seus parâmetros. Quase sempre você usará apenas ParamByName.

Nota: Nem todos os aspectos de uma instrução SQL podem ser parametrizados. Por exemplo, a maioria dos servidores SQL não permite o uso de um parâmetro para o nome da tabela. Considere a seguinte instrução SQL:

• select * from :TableName

Esta instrução resulta em um erro da SQL, pois você não pode usar um parâmetro para o nome da tabela.