.. _orm_genropy/orm_genropy/lettura/query:

query
=====

.. toctree::
   :maxdepth: 1
   :hidden:
   :titlesonly:


   query_metodi



Per leggere il database  :ref:`l'oggetto Table<orm_genropy/approfondimenti/srcobj>`  offre il metodo ``query`` che costruisce l'oggetto **SqlQuery** usando tutta una serie di parametri, tra i quali:

- columns
- where
- order_by
- group_by
- limit
- distinct

che vanno spezzare il classico statement **SQL SELECT** in blocchi. In ognuno dei blocchi possiamo far riferimento ai nomi dei campi o a delle variabili: sarà possibile indicare le colonne con il **$**, le colonne in relazione con la **@**, e le variabili *custom* con i **:**.
              
La sintassi della ``query`` è la seguente::

  myquery = clienti_tbl.query(columns="$ragione_sociale", 
                           where='$provincia = :prov',
                              order_by='$n_fatture',
                           prov='MI')

  print (myquery.sqltext)
  
  SELECT  t0."ragione_sociale" AS "ragione_sociale",
  t0.id AS pkey
  FROM fatt."fatt_cliente" AS t0
  WHERE (t0."provincia" = :prov) AND (t0."__del_ts" IS NULL)
  ORDER BY (  ( SELECT  COUNT(*) AS "COUNT___"
  FROM fatt."fatt_fattura" AS t0_t0
  WHERE (t0_t0."cliente_id"=t0."id") )  )
  
Si noti che il metodo ``query`` si limita a creare l'oggetto **SqlQuery**, ma non eseguirà la query in sé per restituire il risultato. Per questo è necessario fare un passo successivo, ovvero  :ref:`richiederne l'output<orm_genropy/orm_genropy/lettura/query/query_metodi>` 

.. raw:: html

 <hr>

**Parametri:**

+------------------------+------+--------------------------------------------------+
|     Nome parametro     | Tipo |                   Descrizione                    |
+========================+======+==================================================+
|where                   |T     |Permette di indicare la condizione "where" che    |
|                        |      |individuerà i record oggetto della query (es:     |
|                        |      |where='$id=#THIS.id')                             |
+------------------------+------+--------------------------------------------------+
|pkey                    |T     |Alternativamente alla where permette di fornire   |
|                        |      |una pkey come criterio di ricerca (es:            |
|                        |      |pkey=medico_id)                                   |
+------------------------+------+--------------------------------------------------+
|columns                 |T     |Permette di indicare le colonne da restituire come|
|                        |      |risultato dell'interrogazione (es:                |
|                        |      |columns='$fattura_id,$protocollo,$cliente_id')    |
+------------------------+------+--------------------------------------------------+
|for_update              |B     |Se impostato a True il risultato della query sarà |
|                        |      |predisposto per la modifica tramite un'operazione |
|                        |      |di update (es: for_update=True)                   |
+------------------------+------+--------------------------------------------------+
|excludeDraft            |B     |Di default True, se impostato a False permette di |
|                        |      |includere nei risultati gli status "Bozza" (es:   |
|                        |      |excludeDraft=False)                               |
+------------------------+------+--------------------------------------------------+
|excludeLogicalDeleted   |B     |Di default True, se impostato a False permette di |
|                        |      |includere nei risultati i record archiviati o     |
|                        |      |eliminati (es: excludeDraft=False)                |
+------------------------+------+--------------------------------------------------+
|order_by                |T     |Permette di ordinare i risultati della query sulla|
|                        |      |base del parametro indicato (es:                  |
|                        |      |order_by='$fatturato_totale DESC')                |
+------------------------+------+--------------------------------------------------+
|group_by                |T     |Permette di raggruppare i risultati della query   |
|                        |      |sulla base di un determinato criterio (es:        |
|                        |      |group_by='$cliente_id')                           |
+------------------------+------+--------------------------------------------------+
|limit                   |L     |Permette di limitare i risultati della query ai   |
|                        |      |primi n risultati (es: limit=10)                  |
+------------------------+------+--------------------------------------------------+
|offset                  |L     |Il contrario di limit, permette di escludere i    |
|                        |      |primi n elementi indicati (es: offset=5)          |
+------------------------+------+--------------------------------------------------+
|addPkeyColumn           |B     |Di default True, permette di aggiungere           |
|                        |      |automaticamente la colonna 'pkey' ai risultati    |
|                        |      |della query, indipendentemente dalle 'columns'    |
|                        |      |indicate (es: addPkeyColumn=False)                |
+------------------------+------+--------------------------------------------------+

.. sectionauthor:: Davide Paci