GetMyBot नॉलेज बेस

संग्रह और डेटा

GetMyBot में आवेदन, ऑर्डर और बुकिंग को तालिका की तरह सहेजकर रिएक्शन में उपयोग करें।

इस पृष्ठ पर

संग्रह तालिका जैसा है: एक पंक्ति में एक आवेदन, ऑर्डर या कक्षा की बुकिंग रखी जाती है। बॉट उपयोगकर्ताओं के उत्तरों से पंक्तियां जोड़ सकता है। आप उन्हें डेटा → संग्रह में देख और संपादित कर सकते हैं।

मसलन, परामर्श की बुकिंग के लिए leads संग्रह में name, phone, topic फ़ील्ड बनाएं। सवाल पूछने के बाद बॉट नाम, फ़ोन और विषय एक पंक्ति में सहेज देगा। बाद में रिकॉर्ड खोजकर रिएक्शन में इस्तेमाल करें।

संग्रह क्या है

फ़ील्ड ‘फ़ोन’ और ‘विषय’ जैसे कॉलम तय करते हैं। रिकॉर्ड एक पंक्ति का डेटा है। फ़ील्ड और उनके प्रकार की सूची स्कीमा कहलाती है। तकनीकी रूप से रिकॉर्ड JSON दस्तावेज़ है, इसलिए नया फ़ील्ड जोड़ने के लिए पहले से सहेजी पंक्तियां दोबारा बनाने की ज़रूरत नहीं।

संग्रह का नाम बॉट के भीतर अलग होना चाहिए। leads, orders, scores जैसे नाम रिएक्शन की क्रियाओं में पहचान के लिए उपयोग होते हैं।

फ़ील्ड के प्रकार

प्रकारक्या रखता हैउदाहरण
textटेक्स्टनाम, ईमेल, टिप्पणी
numberसंख्याराशि, मात्रा, अंक
boolहाँ/नहीं: true / falseऑर्डर का भुगतान हुआ या नहीं
datetimeतारीख और समयकक्षा का समय
jsonअंदर वस्तु या सूचीउत्पादों के गुणों वाला ऑर्डर

प्रकार के अनुसार इंटरफ़ेस फ़ील्ड संपादित करता और सहेजते समय मान बदलता है। स्कीमा सख्त नहीं है: रिकॉर्ड में स्कीमा से बाहर फ़ील्ड आए तो वह भी सहेजा जाएगा और अलग कॉलम में दिखेगा।

संग्रह बनाना

  1. डेटा → संग्रह खोलकर जोड़ें दबाएं।
  2. नाम लैटिन अक्षरों में बिना खाली जगह के दें ताकि रिएक्शन में इस्तेमाल आसान हो।
  3. फ़ील्ड बटन से कॉलम जोड़ें और हर एक का प्रकार चुनें।
  4. ज़रूरत हो तो नीचे दिए संग्रहण नियम तय कर सहेजें।

रिकॉर्ड देखना और बदलना

संग्रह के कार्ड पर तालिका चिह्न से उस संग्रह की डेटा विंडो खुलती है:

  • देखें: नई पंक्तियां पहले, हर मान अलग सेल में।
  • रिकॉर्ड जोड़ें: स्कीमा के अनुसार फ़ॉर्म; bool के लिए स्विच और json के लिए JSON इनपुट जैसे नियंत्रण।
  • संपादित करें (पेंसिल): मौजूदा पंक्ति बदलें।
  • हटाएं (कूड़ेदान): पंक्ति हटाएं।

बॉट की क्रियाएं भी इन्हीं रिकॉर्ड में अपने आप लिखती हैं। हाथ से संपादन और स्वचालित रिकॉर्डिंग एक ही संग्रह में होती है।

संग्रहण अवधि (retention)

संग्रह अनंत तक न बढ़े, इसलिए सफ़ाई के नियम दें:

  • अधिकतम रिकॉर्ड: सीमा से अधिक होने पर सबसे पुरानी पंक्तियां हटेंगी।
  • अधिकतम दिन तक रखें: तय अवधि से पुराने रिकॉर्ड हटेंगे।

उदाहरण के लिए अस्थायी लॉग 30 दिन रखें। सफ़ाई समय-समय पर होती है, अवधि पूरी होने के ठीक क्षण नहीं। दोनों सीमाएं एक साथ लगा सकते हैं। जिन ऑर्डर की अभी ज़रूरत है, उन पर समय के आधार पर हटाने का नियम न लगाएं।

रिएक्शन से डेटा इस्तेमाल करना

रिएक्शन की क्रियाओं में:

  • रिकॉर्ड बनाएं: {{user_id}} और {{text}} जैसे प्रतिस्थापन से पंक्ति जोड़ता है। डुप्लिकेट रोकने की कुंजी हो तो उसी कुंजी पर दोबारा चलने से नई पंक्ति की जगह पुरानी अपडेट होती है। उपयोगकर्ता ID से हर व्यक्ति का एक ताज़ा आवेदन रख सकते हैं।
  • रिकॉर्ड अपडेट करें: शर्त से मिलती पंक्तियां बदलता है।
  • रिकॉर्ड खोजें: पंक्तियां सूची के रूप में निष्पादन कॉन्टेक्स्ट में लाता है।
  • Read collection page (record_page): रिकॉर्ड छोटे हिस्सों में पढ़ता है, जैसे दो कार्ड और ‘अगला पृष्ठ’ बटन।
  • Aggregate whole collection (record_aggregate): संग्रहण नियमों में आने वाले सभी मेल खाते रिकॉर्ड की संख्या और कुल राशि निकालता है। केवल पहला पृष्ठ लोड होने से गणना सीमित नहीं होती।
  • Atomic collection transaction (collection_transaction): शर्तें जाँचकर कई बदलाव एक साथ सहेजता है, जैसे आखिरी सीट रोकना और आवेदन बनाना। टकराव पर पहले बदलाव भी वापस होते हैं।
  • रिकॉर्ड हटाएं: शर्त से मिलती पंक्तियां हटाता है।
  • सूची पर लूप (for-each): कॉन्टेक्स्ट की सूची में हर आइटम पर रिकॉर्ड बदलना, कुल निकालना या बाहरी सेवा को भेजना जैसी अंदर की क्रियाएं चलाता है।

इस तरह बॉट बिना बाहरी डेटाबेस के CRM, आवेदन, अंक और रिपोर्ट संभाल सकता है। व्यावहारिक पाठ में कैटलॉग का अगला हिस्सा, सभी मेल खाते ऑर्डर का कुल और आखिरी जगह की बुकिंग दिखाई गई है। लोड सूची का पृष्ठ, संग्रह का पृष्ठ और संग्रह का पूरा कुल अलग चीज़ें हैं; पाठ बताते हैं कि अगला चरण कौन-सा डेटा पाता है।

लूप सामूहिक संदेश भेजने के लिए नहीं है। एक बार में अधिकतम 500 आइटम पढ़ता है, लेकिन एक इवेंट कुल अधिकतम 50 संदेश भेज सकता है। हर आइटम पर संदेश भेजने से पहले 50 पहुँच सकते हैं, बाकी विफल होंगे। संग्रह के लोगों को लिखना हो तो सेगमेंट बनाकर ब्रॉडकास्ट भेजें, जिसमें गति, विराम और भेजे जाने का हिसाब रहता है। एक इवेंट का बजट देखें।

कैटलॉग: खोज, चयन और कार्ड

पहले कक्षा खोजने का पाठ पढ़ें। उसमें संग्रह की तैयारी, क्रियाओं का क्रम, खाली परिणाम, कई मेल और पुराने बटन की जाँच बताई गई है।

कैटलॉग का डेटा रिएक्शन से अलग रखें। उदाहरण: products में name, aliases और variants में product_id, name, card हैं। variants.product_id के एडिटर में दूसरे संग्रह से संबंध चालू कर products, कुंजी _record_id और नाम दिखाने वाला फ़ील्ड name चुनें। संबंध फ़ील्ड का अर्थ बताता है; जुड़े रिकॉर्ड अपने आप श्रृंखला में अपडेट या डिलीट नहीं होते।

  1. आने वाले टेक्स्ट पर रिएक्शन में संग्रह में खोजें (record_search) जोड़ें। products, क्वेरी {{text}}, खोज फ़ील्ड name, समानार्थक फ़ील्ड aliases और परिणाम नाम search रखें। समानार्थक टेक्स्ट या JSON की स्ट्रिंग सूची हो सकते हैं। खोज अक्षरों के केस और रूसी е/ё में अंतर नहीं करती; विराम चिह्नों को खाली जगह से बदलती है।
  2. search परिणाम वाला अगला चरण चुनें (branch_result) जोड़ें। पहली मेल खाती शाखा चलती है। पहले अधूरे परिणाम पर और साफ़ खोज पूछें, फिर कुछ नहीं मिला, लगभग मेल, एक रिकॉर्ड, कई रिकॉर्ड संभालें। लगभग मेल पर पुष्टि मांगें। खाली या एक परिणाम मानने के लिए पूरी खोज होना ज़रूरी है।
  3. कई परिणाम के संदेश में मिले रिकॉर्ड से बटन खोलें। स्रोत search, बटन का नाम name और अगला रिएक्शन चुनें। सहायक buttons_from.over = search.rows, नाम का टेम्पलेट और carry.selected_id = {{item._record_id}} भरता है। नाम वाला फ़ील्ड परिणाम में मौजूद हो। विस्तृत बटन एडिटर भी उपलब्ध रहता है।
  4. अगले रिएक्शन में संबंधित रिकॉर्ड खोजें (record_related) जोड़ें: संग्रह variants, कुंजी product_id, मान {{ctx.selected_id}}, परिणाम variants। चुना उत्पाद स्वयं पढ़ने के लिए products और _record_id इस्तेमाल करें। संबंध किसी व्यावसायिक कुंजी में है तो बटन सहायक और पढ़ने वाली क्रिया में वही कुंजी चुनें।
  5. फिर परिणाम पर शाखा चुनें। एक रिकॉर्ड को {{ctx.variants.first.card}} से कार्ड की तरह दिखाएं और कई विकल्प बटन से। हर बटन केवल ID ले जाता है; क्लिक के बाद ताज़ा डेटा पढ़ें। बदल सकने वाला कार्ड या अन्य फ़ील्ड carry में न रखें।

पढ़ने का परिणाम

search.rows रिकॉर्ड की समतल सूची, search.count लोड पंक्तियों की संख्या, search.first पहला रिकॉर्ड और search.first.name उसका फ़ील्ड है। हर पंक्ति में _record_id, _score और _match_type जोड़े जाते हैं; ये नाम आरक्षित हैं। रिकॉर्ड न हों तो पिछला पहला रिकॉर्ड और उसके फ़ील्ड साफ़ हो जाते हैं।

search.total जाँचे गए उम्मीदवारों में मेल गिनता है। total_exact = false का अर्थ पूरा संग्रह नहीं जाँचा गया; truncated = true बताता है परिणाम सीमित है। ऐसे परिणाम को पूरा मानना या संग्रह का सबसे अच्छा मेल मिल जाने का दावा करना सही नहीं। एक अनुरोध में अधिकतम 10 000 रिकॉर्ड और 16 MiB डेटा जाँचे जाते हैं; उत्तर में वास्तविक सीमा आती है। डिफ़ॉल्ट अधिकतम 100 पंक्तियां लौटती हैं, उच्चतम सीमा 10 000 है।

जाँच और कारण

खोज एडिटर में खोज जाँचें खोलकर नमूना टेक्स्ट या ID डालें। यह केवल पढ़ता है: आगे की क्रियाएं, संदेश या रिएक्शन नहीं चलते। अतिरिक्त फ़िल्टर के प्रतिस्थापन पहले वास्तविक मानों से बदलें। जाँच में पंक्तियां, मेल का प्रकार, जाँचे रिकॉर्ड और सीमाएं दिखेंगी। प्रोजेक्ट, संग्रह, सेटिंग या पहुँच बदलने पर पुराने परिणाम छिप जाते हैं।

चलने के लॉग में खोज फ़ील्ड, मेल का प्रकार, जाँची और लौटाई पंक्तियां, परिणाम सीमा तथा चुनी शाखा दिखती है। रिएक्शन के नक्शे में एक रिएक्शन तक जाने वाली सभी शर्तें दिखती हैं। रिकॉर्ड किए रन का इवेंट खोलने पर, यदि उसकी सामग्री देखने का अधिकार है, तो खोज का स्पष्टीकरण दिखता है।

बटन सहायक डिफ़ॉल्ट अधिकतम 20 बटन बनाता है। अधिकतम बटन को 1 से 100 तक बदल सकते हैं; यह पृष्ठ बदलना नहीं, केवल संख्या सीमा है। खाली सूची बटन नहीं बनाती। अधिक परिणाम के लिए खोज स्पष्ट करने वाली शाखा जोड़ें।

गणना क्रिया का लोड सूची पर क्रिया सहायक रिकॉर्ड की संख्या, पहला रिकॉर्ड, किसी फ़ील्ड का कुल और नाम सूची के फ़ॉर्मूले बनाता है। यह केवल लोड पंक्तियां गिनता है; परिणाम अधूरे हों तो पूरे संग्रह का कुल नहीं है।

API और MCP

यही काम POST /api/bots/{botID}/collections/{name}/search और /related, तथा collections:read अधिकार वाले MCP टूल search_records और related_records से कर सकते हैं। कॉल मौजूदा प्रोजेक्ट और क्षेत्र तक सीमित हैं। REST जाँच में ठोस मान जाते हैं, जबकि टेम्पलेट प्रतिस्थापन रिएक्शन की क्रियाओं में होता है।

परिणाम प्रोसेस करना और सशर्त बदलाव

संग्रह का परिणाम list_transform में देकर पंक्तियां छाँटें, क्रम दें, डुप्लिकेट हटाएं या पृष्ठ लें। list_aggregate लोड पंक्तियों का नाम वाला कुल निकालता है, चाहें तो समूह बनाकर। दोनों HTTP उत्तर की सामान्य सूची पर भी चलते हैं, संग्रह ज़रूरी नहीं।

दो एक साथ चले रन एक ही स्थिति बदलाव दो बार न करें, इसके लिए record_update_if उपयोग करें: ID, अपेक्षित फ़ील्ड और नए मान बताएं। एक रिकॉर्ड की जाँच और बदलाव साथ में, परमाणु रूप से होते हैं। मिले परिणाम updated, conflict, not_found को branch_value से सँभालें। यह फ़िल्टर में आए सभी रिकॉर्ड को बिना शर्त बदलने से अलग है। सेटिंग और सीमा देखें।

आवेदन एक ही बार पक्का करने का पाठ स्थिति और स्वामी की जाँच तथा updated, conflict, not_found के अलग जवाब समझाता है।

Mini App से पहुँच

बॉट का Telegram Mini App नाम से संग्रह के रिकॉर्ड, फ़िल्टर और संख्या सीमा के साथ पढ़ सकता है। इससे उपयोगकर्ता Telegram में अपने ऑर्डर, इतिहास या लीडरबोर्ड देखता है।

सुझाव

  • email, total, paid जैसे छोटे लैटिन फ़ील्ड नाम रखें ताकि रिएक्शन टेम्पलेट में आसानी हो।
  • क्रिया दोहराने पर नई पंक्ति न बने, इसके लिए डुप्लिकेट रोकने की कुंजी रखें। इसे idempotency कहते हैं।
  • अस्थायी डेटा और लॉग जो अब ज़रूरी नहीं, उनके लिए संग्रहण अवधि (retention) तय करें।
  • मान की संरचना पहले से न मालूम हो तो json प्रकार चुनें।