mirror of
https://github.com/php/doc-pt_br.git
synced 2026-03-24 15:12:23 +01:00
286 lines
9.4 KiB
XML
286 lines
9.4 KiB
XML
<?xml version="1.0" encoding="utf-8"?><!-- EN-Revision: 51610360d58ed09bc9d1312f419057c0d1d1a998 Maintainer: leonardolara Status: ready --><!-- CREDITS: leonardolara -->
|
||
<refentry xml:id="pdo-sqlite.createaggregate" xmlns="http://docbook.org/ns/docbook">
|
||
<refnamediv>
|
||
<refname>Pdo\Sqlite::createAggregate</refname>
|
||
<refpurpose>
|
||
Registra uma função de agregação definida pelo usuário para uso em instruções SQL
|
||
</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsect1 role="description">
|
||
&reftitle.description;
|
||
<methodsynopsis role="Pdo\\Sqlite">
|
||
<modifier>public</modifier> <type>bool</type><methodname>Pdo\Sqlite::createAggregate</methodname>
|
||
<methodparam><type>string</type><parameter>name</parameter></methodparam>
|
||
<methodparam><type>callable</type><parameter>step</parameter></methodparam>
|
||
<methodparam><type>callable</type><parameter>finalize</parameter></methodparam>
|
||
<methodparam choice="opt"><type>int</type><parameter>numArgs</parameter><initializer>-1</initializer></methodparam>
|
||
</methodsynopsis>
|
||
<simpara>
|
||
Este método é semelhante a <methodname>Pdo\Sqlite::createFunction</methodname>
|
||
exceto que registra funções que podem ser usadas para calcular um
|
||
resultado agregado em todas as linhas de uma consulta.
|
||
</simpara>
|
||
<simpara>
|
||
A principal diferença entre este método e
|
||
<methodname>Pdo\Sqlite::createFunction</methodname>
|
||
é que duas funções são necessárias para gerenciar a agregação.
|
||
</simpara>
|
||
<tip>
|
||
<simpara>
|
||
Usando este método é possível substituir funções SQL nativas.
|
||
</simpara>
|
||
</tip>
|
||
</refsect1>
|
||
|
||
<refsect1 role="parameters">
|
||
&reftitle.parameters;
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><parameter>name</parameter></term>
|
||
<listitem>
|
||
<simpara>
|
||
O nome da função usada nas instruções SQL.
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>step</parameter></term>
|
||
<listitem>
|
||
<simpara>
|
||
Função de retorno de chamada chamada para cada linha do conjunto de resultados.
|
||
O retorno de chamada deve acumular o resultado e armazená-lo no contexto de agregação.
|
||
</simpara>
|
||
<para>
|
||
Esta função precisa ser definida como:
|
||
<methodsynopsis>
|
||
<type>mixed</type><methodname><replaceable>step</replaceable></methodname>
|
||
<methodparam><type>mixed</type><parameter>context</parameter></methodparam>
|
||
<methodparam><type>int</type><parameter>rownumber</parameter></methodparam>
|
||
<methodparam><type>mixed</type><parameter>value</parameter></methodparam>
|
||
<methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>
|
||
</methodsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><parameter>context</parameter></term>
|
||
<listitem>
|
||
<simpara>
|
||
&null; para a primeira linha; nas linhas subsequentes terá o valor
|
||
que foi retornado anteriormente da função step; deve-se usar
|
||
isso para manter o estado agregado.
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>rownumber</parameter></term>
|
||
<listitem>
|
||
<simpara>
|
||
O número da linha atual.
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>value</parameter></term>
|
||
<listitem>
|
||
<simpara>
|
||
O primeiro argumento passado para o agregado.
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>values</parameter></term>
|
||
<listitem>
|
||
<simpara>
|
||
Outros argumentos passados para o agregado.
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
O valor de retorno desta função será usado como argumento
|
||
<parameter>context</parameter> na próxima chamada das funções step
|
||
ou finalize.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>finalize</parameter></term>
|
||
<listitem>
|
||
<simpara>
|
||
Função de retorno de chamada para agregar os dados "escalonados" de cada linha.
|
||
Depois que todas as linhas forem processadas, esta função será chamada,
|
||
devendo então pegar os dados do contexto de agregação e retornar o resultado.
|
||
Esta função de retorno de chamada deve retornar um tipo compreendido pelo SQLite
|
||
(ou seja, <link linkend="language.types.intro">tipo escalar</link>).
|
||
</simpara>
|
||
<para>
|
||
Esta função precisa ser definida como:
|
||
<methodsynopsis>
|
||
<type>mixed</type><methodname><replaceable>fini</replaceable></methodname>
|
||
<methodparam><type>mixed</type><parameter>context</parameter></methodparam>
|
||
<methodparam><type>int</type><parameter>rowcount</parameter></methodparam>
|
||
</methodsynopsis>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><parameter>context</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Contém o valor de retorno da última chamada para a função step.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>rowcount</parameter></term>
|
||
<listitem>
|
||
<para>
|
||
Contém o número de linhas nas quais a agregação foi executada.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
O valor de retorno desta função será usado como valor de retorno
|
||
da agregação.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term><parameter>numArgs</parameter></term>
|
||
<listitem>
|
||
<simpara>
|
||
Dica para o analisador SQLite se a função de retorno de chamada
|
||
aceita um número predeterminado de argumentos.
|
||
</simpara>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect1>
|
||
|
||
<refsect1 role="returnvalues">
|
||
&reftitle.returnvalues;
|
||
<simpara>
|
||
&return.success;
|
||
</simpara>
|
||
</refsect1>
|
||
|
||
<refsect1 role="examples">
|
||
&reftitle.examples;
|
||
<example>
|
||
<title>Exemplo de <methodname>Pdo\Sqlite::createAggregate</methodname></title>
|
||
<simpara>
|
||
Neste exemplo, criaremos uma função agregada personalizada chamada
|
||
<literal>max_length</literal> que pode ser usada em consultas SQL.
|
||
</simpara>
|
||
<simpara>
|
||
Neste exemplo, estamos criando uma função agregadora,
|
||
chamada <literal>max_length</literal>, que calculará o comprimento
|
||
da string mais longa em uma das colunas da tabela.
|
||
Para cada linha, a função <literal>max_len_step</literal> é chamada e
|
||
passa um parâmetro <literal>$context</literal>.
|
||
O parâmetro context é como qualquer outra variável PHP e pode ser configurado para
|
||
conter um <type>array</type> ou até mesmo um <type>object</type>.
|
||
Neste exemplo, estamos usando-o para manter o comprimento máximo que vimos até agora;
|
||
se <varname>$string</varname> tiver um comprimento maior que o máximo atual,
|
||
atualizamos o contexto para manter esse novo comprimento máximo.
|
||
</simpara>
|
||
<simpara>
|
||
Após todas as linhas terem sido processadas,
|
||
o SQLite chama a função <literal>max_len_finalize</literal> para determinar
|
||
o resultado agregado.
|
||
É possível realizar algum tipo de cálculo baseado nos dados em <literal>$context</literal>.
|
||
Neste exemplo básico o resultado foi calculado à medida que a consulta avançava,
|
||
para que o valor do contexto pudesse ser retornado diretamente.
|
||
</simpara>
|
||
<programlisting role="php">
|
||
<![CDATA[
|
||
<?php
|
||
$data = [
|
||
'one',
|
||
'two',
|
||
'three',
|
||
'four',
|
||
'five',
|
||
'six',
|
||
'seven',
|
||
'eight',
|
||
'nine',
|
||
'ten',
|
||
];
|
||
$db = new Pdo\Sqlite('sqlite::memory:');
|
||
$db->exec("CREATE TABLE strings(a)");
|
||
$insert = $db->prepare('INSERT INTO strings VALUES (?)');
|
||
foreach ($data as $str) {
|
||
$insert->execute(array($str));
|
||
}
|
||
$insert = null;
|
||
|
||
function max_len_step($context, $row_number, $string)
|
||
{
|
||
if (strlen($string) > $context) {
|
||
$context = strlen($string);
|
||
}
|
||
return $context;
|
||
}
|
||
|
||
function max_len_finalize($context, $row_count)
|
||
{
|
||
return $context === null ? 0 : $context;
|
||
}
|
||
|
||
$db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');
|
||
|
||
var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());
|
||
|
||
?>
|
||
]]>
|
||
</programlisting>
|
||
<!-- TODO
|
||
&example.outputs;
|
||
<screen>
|
||
<![CDATA[
|
||
Code example
|
||
]]>
|
||
</screen>
|
||
-->
|
||
<tip>
|
||
<simpara>
|
||
NÃO é recomendado que se armazene uma cópia dos valores no contexto
|
||
e depois processe-os no final, pois faria com que o SQLite usasse muita
|
||
memória para processar a consulta - basta pensar em quanta memória seria necessárias
|
||
se um milhão de linhas fossem armazenadas na memória, cada uma contendo uma string de 32 bytes
|
||
de comprimento.
|
||
</simpara>
|
||
</tip>
|
||
</example>
|
||
</refsect1>
|
||
|
||
<refsect1 role="seealso">
|
||
&reftitle.seealso;
|
||
<simplelist>
|
||
<member><methodname>Pdo\Sqlite::createFunction</methodname></member>
|
||
<member><methodname>Pdo\Sqlite::createCollation</methodname></member>
|
||
<member><function>sqlite_create_function</function></member>
|
||
<member><function>sqlite_create_aggregate</function></member>
|
||
</simplelist>
|
||
</refsect1>
|
||
|
||
</refentry>
|
||
<!-- Keep this comment at the end of the file
|
||
Local variables:
|
||
mode: sgml
|
||
sgml-omittag:t
|
||
sgml-shorttag:t
|
||
sgml-minimize-attributes:nil
|
||
sgml-always-quote-attributes:t
|
||
sgml-indent-step:1
|
||
sgml-indent-data:t
|
||
indent-tabs-mode:nil
|
||
sgml-parent-document:nil
|
||
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
||
sgml-exposed-tags:nil
|
||
sgml-local-catalogs:nil
|
||
sgml-local-ecat-files:nil
|
||
End:
|
||
vim600: syn=xml fen fdm=syntax fdl=2 si
|
||
vim: et tw=78 syn=sgml
|
||
vi: ts=1 sw=1
|
||
-->
|