.. _gnrextra/ltx/modalita_uso:

Modalità d'uso
==============




L’attributo di colonna ``ext_ltx`` abilita le funzionalità LTX (Large Text eXtension) di Genropy, che permettono la gestione di testi di grandi dimensioni, metadati estratti e indicizzazione full-text.

Può essere configurato in due modalità principali:
	•	*local* → i dati testuali e i metadati vengono memorizzati nella stessa tabella che definisce la colonna.
	•	*document* → i dati testuali e i metadati vengono memorizzati nella tabella esterna ``ltx.document``, con un collegamento tramite *foreign key*.

Modalità Local
---------------

Sintassi::

  tbl.column('testo', ext_ltx=True)
  tbl.column('testo', ext_ltx='italian')
  tbl.column('testo', ext_ltx='local:italian')
  
Caratteristiche principali:

	•	Tutto è self-contained nella tabella corrente.
	•	ext_config() aggiunge automaticamente:
	•	<campo>_text → testo indicizzato.
	•	<campo>_language → lingua del testo (se non specificata).
	•	<campo>_tsv → vettore tsvector per indicizzazione full-text PostgreSQL.
	•	<campo>_extracted_metadata → metadati strutturati.
	•	<campo>_extraction_ts → timestamp estrazione.
	•	<campo>_extract_error, <campo>_snippet, <campo>_rank → info di ricerca.
	•	Mixin associato: **LTXLocalTableMixin**
    
Gestisce:

	•	Aggiornamento automatico della lingua (langdetect).
	•	Pulizia dei metadati quando cambia il testo.
	•	Reset dei campi legati all’estrazione se il contenuto viene modificato.

Quando usarla:

	•	Testo puro inserito manualmente o derivato da altri dati.
	•	Non serve gestire file binari o OCR.
	•	Vuoi tenere tutto nella stessa tabella per semplicità.


Modalità Document
-----------------

Sintassi::

   tbl.column('file', ext_ltx='document:italian')
   tbl.column('file', ext_ltx='*:italian')  

Caratteristiche principali:

	•	Il testo, i metadati e l’eventuale file sorgente sono gestiti nella tabella ``ltx.document``.
	•	ext_config() rimanda a plugColumnToDocument() che:
	•	Crea una foreign key verso ltx.document.
	•	Registra il mapping chiave primaria ↔ chiave esterna documento in ``ltx_document_connection``.
	•	Aggiunge una colonna ``<campo>_ltx_document_id`` per join diretta con ltx.document.
	•	Mixin associato: **LTXRelatedTableMixin**
Gestisce:
	•	Creazione/aggiornamento record in ltx.document.
	•	Registrazione parametri (**ltx_documentRegister**) come nome, lingua, preprocess (OCR, estrazione).
	•	Supporto file binari (pdf, jpg, ecc.) con OCR automatico se configurato.
	•	Memorizzazione hash del file per evitare rielaborazioni inutili.

Quando usarla:
	•	Devi gestire file binari (PDF, immagini, ecc.).
	•	Vuoi centralizzare in ltx.document la gestione di testi, OCR, metadati e indicizzazione.
	•	Vuoi condividere lo stesso documento tra più tabelle o record.

.. sectionauthor:: Davide Paci