DNATech :: 🗡️ TCSQLExec x TCQuery :: Quando o SQL é pesado, não force o ADVPL a carregar o piano

_Créditos da imagem: ChatGPT

Se a query parece coisa de DBA, **ela é coisa de DBA**.
Exemplo real, sem dó:

👉 Query com **PIVOT, agregações, períodos, centro de custo e grupo**
👉 Caso clássico para **TCSQLExec**:
[https://raw.githubusercontent.com/naldodj/naldodj-totvsGetDataModel/refs/heads/main/scripts/sql/mssql/pivot-painel-acumulados-periodo-centro-de-custo-grupo.sql](https://raw.githubusercontent.com/naldodj/naldodj-totvsGetDataModel/refs/heads/main/scripts/sql/mssql/pivot-painel-acumulados-periodo-centro-de-custo-grupo.sql)

Isso aqui:

* não é consulta simples
* não é leitura transacional
* não é “SQLzinho”

É **SQL analítico**, feito para o banco resolver de uma vez.

👉 **Use `TCSQLExec`**
Deixe o SQL Server / Oracle pensar.
O AppServer agradece.

---

## 🥋 E o TCQuery entra onde?

Depois que o **TCSQLExec**:

* gerou uma tabela
* alimentou uma temporária
* criou uma view
* ou populou um staging

👉 você usa **TCQuery para navegar pelos resultados**:

* alias navegável
* `DbSkip()`
* `EOF()`
* integração total com ADVPL
* zero lógica pesada no loop

Ou seja:

> **TCSQLExec calcula. TCQuery apresenta.**

Esse é o combo ninja. 🥷

---

## ⚠️ Atenção: TCQuery NÃO é função

Isso aqui é importante e muita gente erra.

❌ **TCQuery não é função ADVPL**
✅ É uma **instrução do pré-processador**

Ela vem definida no **`topconn.ch`**, junto com outros comandos do TopConn.
Ou seja:

* o pré-compilador transforma isso
* em chamadas internas (ex: `dbUseArea`,`TCGenQry`,etc. Consulte topconn.ch para maiores referências)
* antes do código virar executável

Confundir comando de pré-processador com função da linguagem é erro conceitual clássico de quem “só usa” e não entende a stack.

---

## 🧠 Não existe só TCQuery e TCSQLExec

Outro ponto de maturidade:
o Protheus **não limita você a duas opções**.

Vale consultar o TDN e conhecer outras abordagens, como:

* **FWTemporaryTable**
  [https://tdn.totvs.com/display/public/framework/FWTemporaryTable](https://tdn.totvs.com/display/public/framework/FWTemporaryTable)

* **MPSysOpenQuery**
  [https://tdn.totvs.com/display/public/framework/MPSysOpenQuery](https://tdn.totvs.com/display/public/framework/MPSysOpenQuery)

* Dentre outras...

Cada uma tem:

* propósito
* custo
* impacto
* cenário ideal

Não existe bala de prata.
Existe **decisão técnica bem tomada**.

---

## 📌 Regra de ouro (versão definitiva)

> **Se a lógica pertence ao banco → TCSQLExec**
> **Se o resultado precisa ser navegado no ADVPL → TCQuery**
> **Se tiver dúvida → consulte o TDN da TOTVS**

Menos improviso.
Mais arquitetura.
Clássico no conceito, moderno na execução.

Estilo ninja. 🥷🔥

---

#ADVPL #Protheus #TOTVS #SQLNoProtheus #TCQuery #TCSQLExec #TopConn #Performance #DicaNinja #DevSenior #ERP

Torne-se um Sponsor: 🥊(дави)={0.5x[(Налдо)+(Алине)]}🥊