.. _orm_genropy/orm_genropy/lettura/record_readcolumns:

record e readColumns
====================




Se sappiamo che il risultato della nostra operazione di interrogazione sarà un unico *record* che siamo interessati a leggere o modificare, Genropy ci offre uno strumento semplificato, la ``record``::

  cliente_rec = tbl_cliente.record(cliente_id, for_update=True).output('bag')
  
In questo caso individuo il record direttamente dalla sua ``id``, ma avremmo potuto passare qualsiasi altro parametro che conducesse ad un risultato univoco, ad es::
  
  bot = self.db.table('genrobot.bot').record(api_token=token, ignoreDuplicate=True, ignoreMissing=True).output('record')
  
.. hint::
  Si noti che con il parametro ``ignoreMissing=True`` evitiamo di mandare il sistema in errore in caso di mancanza di un risultato, mentre con ``ignoreDuplicate=True`` evitiamo l'errore in caso ci fosse più di un risultato (scegliendo come unico valido il primo presentato).

Il metodo ``record`` non ritorna direttamente i dati, ma è necessario richiederne l'output sotto forma di::

  .output('bag')
  .output('dict')
  .output('record')
  
Il metodo ritornerà solo le colonne "vere" del record, ad esclusione quindi delle  :ref:`Colonne virtuali<orm_genropy/virtual_columns/virtual_columns>`  (a meno che non venga specificato il parametro ``virtual_columns`` come descritto nella sezione dedicata).

.. 
  relationDict=None, 
  joinConditions=None, 
  sqlContextName=None,
  _storename=None,
  checkPermissions=False,
  aliasPrefix=None,
  
        :param lazy: TODO
        :param eager: TODO
        :param mode: bag, dict, json
        :param relationDict: a dict to assign a symbolic name to a :ref:`relation_path`. For more information
                             check the :ref:`relationdict` documentation section
        :param joinConditions: special conditions for joining related tables. See the
                               :meth:`setJoinCondition() <gnr.sql.gnrsqldata.SqlQuery.setJoinCondition()>` method
        :param sqlContextName: TODO
        :param for_update: TODO"""
        
Una record abbreviata: readColumns
----------------------------------
Restituisce l'elenco dei valori di colonna risultanti da una tradizionale query sql di tipo SELECT.

Di fatto è come fare una query con questi valori di default:

- where, pkeys e columns
- limit=1
- addPkeyColumn=False
- excludeDraft=False
- ignorePartition=True
- excludeLogicalDeleted=False

La sintassi della *readColumns* è la seguente::
  
  totale_lordo, totale_iva = self.db.table('fatt.fattura_riga').readColumns(columns="""SUM($prezzo_totale) AS totale_lordo,
                    SUM($iva) AS totale_iva""", where='$fattura_id=:f_id', f_id=fattura_id)
                                                                                 
.. hint
  Essendo di fatto una query, si noti che possono essere usati TUTTI i parametri che vengono usati nel caso precedente

.. 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)                |
+------------------------+------+--------------------------------------------------+
|mode                    |T     |Permette di specificare l'output tra 'bag',       |
|                        |      |'dict', 'json' e 'record'. Es: mode='bag' equivale|
|                        |      |a specificare .output('bag')                      |
+------------------------+------+--------------------------------------------------+
|virtual_columns         |T     |Permette di aggiungere una serie di colonne       |
|                        |      |virtuali (aliasColumn, formulaColumn) che         |
|                        |      |altrimenti non verrebbero considerate nel record  |
|                        |      |(es: virtual_columns='$n_fatture,$tot_fatturato') |
+------------------------+------+--------------------------------------------------+
|eager                   |B     |                                                  |
+------------------------+------+--------------------------------------------------+
|ignoreMissing           |B     |Se impostato a True restituisce un record di      |
|                        |      |valori nulli in caso di record non corrispondente |
|                        |      |alla ricerca effettuata, invece di restituire un  |
|                        |      |errore (es: ignoreMissing=True)                   |
+------------------------+------+--------------------------------------------------+
|ignoreDuplicate         |B     |Se impostato a True verranno ignorati eventuali   |
|                        |      |valori duplicati individuati e verrà considerato  |
|                        |      |solo il primo (es: ignoreDuplicate=True)          |
+------------------------+------+--------------------------------------------------+
|lazy                    |B     |                                                  |
+------------------------+------+--------------------------------------------------+

.. sectionauthor:: Davide Paci