Raccolte e dati
Come conservare richieste, ordini e prenotazioni in GetMyBot: creare una tabella, aggiungere dati e usarli nelle reazioni.
In questa pagina
Una raccolta è simile a una tabella: ogni riga rappresenta una richiesta, un ordine o una prenotazione. Il bot può aggiungere righe dalle risposte degli utenti; tu puoi consultarle e modificarle in Dati → Raccolte.
Per esempio, per prenotare consulenze crea la raccolta leads con i campi name, phone e topic. Dopo le domande, il bot salva nome, telefono e argomento in una riga. In seguito puoi cercarla e usarla in una reazione.
Che cos'è una raccolta
I campi definiscono le colonne, per esempio «Telefono» e «Argomento». Un record contiene i valori di una riga. L'elenco dei campi e dei relativi tipi è detto schema. Tecnicamente un record è conservato come documento JSON: aggiungere un nuovo campo non richiede di ricreare le righe già salvate.
Il nome della raccolta è unico per ciascun bot ed è l'identificatore usato nelle azioni delle reazioni, per esempio leads, orders o scores.
Tipi di campo
Quando crei una raccolta, definisci i campi e il loro tipo:
| Tipo | Valore | Esempio |
|---|---|---|
text | Testo | Nome, email o commento |
number | Numero | Importo, quantità o punti |
bool | Sì o no: true / false | Ordine pagato |
datetime | Data e ora | Orario di una lezione |
json | Oggetto o elenco annidato | Articoli e proprietà di un ordine |
Il tipo determina come il campo viene modificato nell'interfaccia e convertito al salvataggio. Lo schema è flessibile: se un record contiene un campo non definito, questo viene salvato e mostrato in una colonna separata.
Creare una raccolta
- Apri Dati → Raccolte e premi Aggiungi.
- Inserisci un nome in caratteri latini e senza spazi, così sarà facile richiamarlo nelle reazioni.
- Con Campo aggiungi le colonne e scegli il tipo di ciascuna.
- Se necessario, imposta le regole di conservazione descritte sotto e salva.
Consultare e modificare i record
Nella scheda della raccolta, il pulsante con l'icona della tabella apre la finestra Dati con i record:
- Visualizza: mostra le righe, un campo per cella, a partire dalle più recenti.
- Aggiungi record: apre un modulo basato sullo schema; ogni tipo ha il proprio controllo, per esempio un interruttore per
boole un campo JSON perjson. - Modifica (matita): cambia una riga esistente.
- Elimina (cestino): rimuove una riga.
Anche le azioni del bot possono aggiungere record automaticamente. Le modifiche manuali e automatiche riguardano la stessa raccolta.
Conservazione dei dati (retention)
Per evitare che la raccolta cresca senza limiti, imposta la pulizia automatica:
- Numero massimo di record: quando viene superato, i record più vecchi sono eliminati.
- Conserva per non più di (giorni): elimina i record più vecchi del periodo indicato.
Per esempio, 30 giorni possono bastare per un registro temporaneo. La pulizia è periodica, quindi non avviene nell'istante esatto della scadenza. Puoi usare entrambe le regole insieme. Evita una scadenza per gli ordini ancora necessari.
Usare i dati nelle reazioni
Le azioni disponibili nelle reazioni includono:
- Crea record: aggiunge una riga con valori come
{{user_id}}e{{text}}. Una chiave di deduplicazione evita i doppioni: una nuova chiamata con la stessa chiave aggiorna la riga esistente. Usando l'ID utente, per esempio, puoi tenere una sola richiesta aggiornata per persona. - Aggiorna record: modifica le righe che soddisfano una condizione.
- Interroga record: carica le righe nel contesto della reazione come elenco, da elaborare nei passi seguenti.
- Read collection page (
record_page): carica i record a blocchi, per esempio due schede alla volta con un pulsante per la pagina successiva. - Aggregate whole collection (
record_aggregate): conta e somma tutti i record corrispondenti entro le regole di conservazione. Il calcolo non si ferma alla prima pagina caricata. - Atomic collection transaction (
collection_transaction): verifica condizioni e salva più modifiche insieme, per esempio occupa un posto e crea una richiesta. In caso di conflitto, annulla anche le modifiche precedenti. - Elimina record: rimuove le righe che soddisfano una condizione.
- Ciclo (for-each): percorre un elenco nel contesto ed esegue azioni annidate per ogni elemento, per esempio aggiornare righe, calcolare un totale o inviarle a un servizio esterno.
Il bot può così gestire richieste, punti e report senza un database esterno.
Le lezioni pratiche mostrano come continuare un catalogo, calcolare il totale di tutti gli ordini pertinenti e prenotare l'ultimo posto. Una pagina dell'elenco caricato, una pagina della raccolta e un totale dell'intera raccolta danno risultati diversi; le lezioni mostrano quali dati arrivano al passo seguente.
Il ciclo non è uno strumento per gli invii di massa. Può elaborare fino a 500 elementi in un'esecuzione, mentre un intero evento può inviare al massimo 50 messaggi: un ciclo che invia messaggi raggiungerà i primi 50 destinatari e rifiuterà gli altri. Per scrivere alle persone presenti nella raccolta, crea un segmento e invia una campagna, che gestisce velocità, pausa e conteggio degli invii. Dettagli sui limiti: Azioni → Limiti di un evento.
Catalogo: ricerca, scelta e scheda
Per iniziare, segui la lezione sulla ricerca di una lezione. Spiega quali raccolte preparare, in quale ordine aggiungere le azioni e come verificare un risultato vuoto, più corrispondenze e la pressione di un vecchio pulsante.
Per un catalogo, conserva i dati separatamente dalle reazioni. Per esempio, products contiene name e aliases, mentre variants contiene product_id, name e card. Nel campo variants.product_id, attiva Collegamento a un'altra raccolta, seleziona products, la chiave _record_id e il campo etichetta name. Il collegamento descrive a cosa serve il campo; non modifica né elimina automaticamente i record collegati.
- Nella reazione al testo ricevuto aggiungi Cerca nella raccolta (
record_search). Selezionaproducts, la ricerca{{text}}, il camponame, il campo dei sinonimialiasese salva il risultato insearch. I sinonimi possono essere una stringa o un elenco di stringhe JSON. La ricerca ignora maiuscole e minuscole; per il russo considera equivalenti е ed ё e sostituisce la punteggiatura con spazi. - Aggiungi Scegli il passo successivo (
branch_result) con originesearch. Viene eseguito il primo ramo corrispondente. Gestisci prima i Risultati incompleti chiedendo di precisare la ricerca, poi Nessun risultato, Corrispondenza approssimativa, Un record e Più record. Chiedi conferma per una corrispondenza approssimativa. Per distinguere zero o un solo risultato serve una ricerca completa. - Per più risultati, nel messaggio apri Pulsanti dai record trovati. Scegli
search, il campo etichettanamee la reazione successiva. La procedura guidata impostabuttons_from.over = search.rows, il modello dell'etichetta ecarry.selected_id = {{item._record_id}}. Verifica chenamesia fra i campi restituiti. L'editor avanzato del pulsante resta disponibile. - Nella reazione successiva usa Trova record collegati (
record_related): raccoltavariants, chiaveproduct_id, valore{{ctx.selected_id}}, risultatovariants. Per rileggere il record selezionato usaproductse la chiave_record_id. Se il collegamento usa una chiave di business, scegli la stessa chiave sia nei pulsanti sia nell'azione di lettura. - Scegli un altro ramo in base al risultato. Se c'è un solo record, mostra la scheda con
{{ctx.variants.first.card}}; se ce ne sono diversi, mostra dei pulsanti. Ogni pulsante porta l'ID e i dati aggiornati vengono letti dopo il clic. Non mettere incarryla scheda o altri campi che possono cambiare.
Risultato della lettura
search.rows è l'elenco dei record, search.count il numero di righe caricate, search.first il primo record e search.first.name un suo campo. Ogni riga contiene inoltre _record_id, _score e _match_type, nomi riservati. Se non ci sono record, il valore precedente del primo record e dei suoi campi viene cancellato.
search.total conta le corrispondenze fra i candidati esaminati. total_exact = false indica che non è stata esaminata tutta la raccolta; truncated = true segnala un limite nei risultati. In questo caso non puoi considerare il risultato completo né garantire che la migliore corrispondenza dell'intera raccolta sia stata trovata. Ogni richiesta esamina fino a 10 000 record e 16 MiB di dati; la risposta indica i limiti effettivi. Il valore predefinito è 100 righe restituite, il massimo 10 000.
Verifica e spiegazione
Nell'editor della ricerca apri Prova la ricerca e inserisci una stringa o un ID concreto. È una prova di sola lettura: non esegue reazioni, messaggi o azioni successive. Sostituisci prima i segnaposto nei filtri aggiuntivi con valori concreti. La prova mostra righe, tipo di corrispondenza, numero di record esaminati e limiti. I vecchi risultati vengono nascosti se cambiano progetto, raccolta, impostazioni o permessi.
Il registro di esecuzione mostra i campi cercati, il tipo di corrispondenza, i record esaminati e restituiti, i limiti e il ramo scelto. Nello schema della reazione sono indicate tutte le condizioni che conducono alla stessa reazione. Riaprendo una registrazione di esecuzione, la spiegazione della ricerca è disponibile nell'evento corrispondente, se hai il permesso di leggerne il contenuto.
La procedura guidata crea fino a 20 pulsanti per impostazione predefinita. Puoi impostare il Numero massimo di pulsanti da 1 a 100: è un limite, non una paginazione. Un elenco vuoto non crea pulsanti. Per molti risultati, aggiungi un ramo che chieda di precisare la ricerca.
Nell'azione Calcolo, la procedura Operazione sull'elenco caricato prepara formule per numero di record, primo record, somma di un campo ed elenco delle etichette. Calcola solo sulle righe caricate: se i risultati sono incompleti, non rappresenta il totale dell'intera raccolta.
API e MCP
Le stesse operazioni sono disponibili con POST /api/bots/{botID}/collections/{name}/search e /related e con gli strumenti MCP search_records e related_records, che richiedono il permesso collections:read. Le chiamate sono limitate al progetto e alla regione correnti. Nelle prove REST devi fornire valori concreti; le sostituzioni nei modelli vengono elaborate nelle azioni delle reazioni.
Elaborare risultati e modifiche condizionali
Puoi passare il risultato a list_transform per filtrare, ordinare, eliminare duplicati o estrarre una pagina. list_aggregate calcola totali con nomi per le righe caricate, anche raggruppandole. Le stesse azioni funzionano su un elenco ricevuto via HTTP, senza raccolta.
Per evitare che due esecuzioni simultanee ripetano lo stesso cambio di stato, usa record_update_if: specifica ID, valori attesi e nuovi valori. Controllo e modifica sono atomici per un record. Puoi gestire lo stato salvato updated, conflict o not_found con branch_value. È diverso da un aggiornamento incondizionato di tutte le righe che soddisfano un filtro.
Configurazione, limiti ed esempi.
La lezione sulla conferma senza doppioni spiega come verificare stato e proprietario e rispondere separatamente a updated, conflict e not_found.
Accesso da Mini App
Una Telegram Mini App del bot può leggere i record della raccolta: l'interfaccia richiede i dati per nome, con filtri e un limite. Così puoi mostrare ordini, cronologia o classifica direttamente in Telegram.
Consigli
- Usa nomi di campo brevi (
email,total,paid): sono più facili da inserire nei modelli delle reazioni. - Usa la chiave di deduplicazione quando ripetere un'azione non deve creare una nuova riga. Questa proprietà si chiama idempotenza.
- Imposta un periodo di conservazione (
retention) per registri e dati temporanei che non servono più. - Usa
jsonquando la struttura di un valore non è definita in anticipo.