Skip to main content

Database Nodes

Manage and query user data within your bot. These nodes let you search, update, and retrieve user information stored in BotGami's database.

Why Database Nodes?​

Use Cases:

  • 🔍 Search for users by criteria (location, sign-up date, tags)
  • 📊 Build admin dashboards (user lists, statistics)
  • 🔄 Update user metadata (tags, scores, custom fields)
  • 📤 Broadcast to specific user segments

Database nodes workflow showing search → filter → broadcast

🔍 Search Users (db.search_users)​

Find users matching specific criteria from your bot's database.

Configuration​

SettingDescription
FilterQuery conditions (e.g., tags contains "premium")
LimitMax results (default: 100)
SortByField to sort by
SortOrderasc or desc

Inputs​

InputTypeDescription
InFLOWTrigger execution
FilterStringDynamic filter expression
LimitNumberMax results

Outputs​

OutputTypeDescription
NEXTFLOWSearch complete
UsersArrayList of user objects
CountNumberTotal results found
ErrorFLOWQuery failed

Filter Syntax​

Field Operator Value

Examples:
- signup_date > "2024-01-01"
- tags contains "vip"
- last_active < "7 days ago"
- city == "New York"
- age >= 18 and verified == true

User Object Fields​

Each user object contains:

  • user_id — Telegram User ID
  • first_name, last_name, username
  • signup_date — When they started the bot
  • last_active — Last interaction timestamp
  • tags — Array of tags
  • metadata — Custom fields (object)

Example: Find VIP Users​

[db.search_users]
  Filter: tags contains "vip" and last_active > "30 days ago"
  Limit: 50
  SortBy: last_active
  SortOrder: desc
  ↓ Users output
[For Each user in Users]
  ↓
[Send Message to user.user_id]
  Text: "Hey {{user.first_name}}, we miss you! 🎉"

[Screenshot: db.search_users node showing filter configuration]

Example: Admin Dashboard​

Command: /admin stats

[db.search_users]
  Filter: signup_date > "this month"
  ↓ Count
[Send: "📊 New users this month: {{Count}}"]

✏️ Update User (db.update_user)​

Modify user data — add tags, update custom fields, or change metadata.

Configuration​

SettingDescription
UserIDWhich user to update
UpdatesFields to modify

Inputs​

InputTypeDescription
InFLOWTrigger
UserIDNumberTarget user ID
UpdatesObjectFields to update

Outputs​

OutputTypeDescription
SuccessFLOWUpdated
ErrorFLOWFailed
UserObjectUpdated user object

Updatable Fields​

{
  "tags": ["premium", "verified"],  // Replace tags array
  "metadata": {                      // Merge into metadata
    "score": 150,
    "level": 5,
    "subscribed": true
  }
}

Example: Add VIP Tag​

User completes purchase

[db.update_user]
  UserID: {{user.id}}
  Updates: {
    "tags": ["vip", "paying"],
    "metadata": {
      "plan": "premium",
      "upgraded_at": "{{$now()}}"
    }
  }
  ↓ Success
[Send: "✅ Upgraded to VIP!"]

Example: Leaderboard Score​

User wins game

[data.transform]
  Expression: var.score + 10
  ↓
[db.update_user]
  UserID: {{user.id}}
  Updates: {
    "metadata": {
      "score": {{transformed_value}}
    }
  }

[Screenshot: db.update_user showing metadata update]

📥 Get User (db.get_user)​

Retrieve complete user data by User ID.

Inputs​

InputTypeDescription
InFLOWTrigger
UserIDNumberUser to fetch

Outputs​

OutputTypeDescription
FoundFLOWUser exists
NotFoundFLOWUser doesn't exist
UserObjectFull user object

Example: Check User Status​

Admin: Check user 123456

[db.get_user]
  UserID: 123456
  ↓ Found
[Send: "User: {{User.first_name}}
Tags: {{User.tags}}
Last active: {{User.last_active}}"]
  ↓ NotFound
[Send: "User not found in database"]

Common Patterns​

Pattern 1: Segment Broadcast​

Send announcement to all premium users

[db.search_users]
  Filter: tags contains "premium"
  Limit: 1000
  ↓ Users
[For Each user in Users]
  ↓
[action.send]
  ChatID: {{user.user_id}}
  Text: "🎉 Premium-only announcement!"

Pattern 2: User Scoring System​

User answers correctly

[db.get_user]
  UserID: {{user.id}}
  ↓ Found
[data.transform]
  Input: {{User.metadata.score}}
  Expression: ($ or 0) + 10  // Default to 0 if no score
  ↓
[db.update_user]
  Updates: { "metadata": { "score": {{result}} } }
  ↓
[Send: "✅ +10 points! Total: {{result}}"]

Pattern 3: Tag Management​

Command: /tag add vip @username

[Extract username from command]
  ↓
[db.search_users]
  Filter: username == "{{extracted_username}}"
  ↓ Users[0]
[db.get_user]
  UserID: {{Users[0].user_id}}
  ↓ Tags
[data.array_push]
  Array: {{Tags}}
  Item: "vip"
  ↓
[db.update_user]
  Updates: { "tags": {{new_array}} }
  ↓
[Send: "✅ Tagged {{username}} as VIP"]

Pattern 4: Activity Report​

Admin command: /report

[db.search_users]
  Filter: last_active > "7 days ago"
  ↓ Count as active_count
[db.search_users]
  Filter: signup_date > "this month"
  ↓ Count as new_count  

[Send: "📊 Activity Report:
Active (7d): {{active_count}}
New (month): {{new_count}}"]

Filter Examples​

Time-Based​

signup_date > "2024-01-01"
last_active < "30 days ago"
last_active > "this week"

Tag-Based​

tags contains "premium"
tags not contains "banned"
tags in ["vip", "moderator"]

Metadata​

metadata.score > 100
metadata.verified == true
metadata.plan == "premium"

Combined​

tags contains "active" and last_active > "7 days ago" and metadata.score >= 50

Best Practices​

1. Limit Results​

✅ Limit: 100  // Reasonable batch size
❌ Limit: 10000  // May timeout

2. Index Important Fields​

Common search fields (tags, signup_date) are pre-indexed for fast queries.

3. Batch Processing​

For large user lists, use pagination:

[db.search_users] Limit: 100, Offset: 0
Process batch
[db.search_users] Limit: 100, Offset: 100
Process batch
...

4. Error Handling​

[db.update_user]
  ↓ Success
  [Confirm]
  ↓ Error
  [Log error + Notify admin]

5. Tags Strategy​

✅ tags: ["premium", "active", "verified"]
❌ tags: ["premium_2024_01_15_user_123"]  // Too specific

Use metadata for detailed info:

metadata: {
  "plan": "premium",
  "plan_start": "2024-01-15",
  "features": ["feature1", "feature2"]
}

Security Notes​

⚠️ Important: Database nodes should typically be restricted to admin commands or protected flows

Recommended Pattern:

[Command /admin]
  ↓
[logic.condition]
  Expression: user.id in [ADMIN_ID_1, ADMIN_ID_2]
  ↓ True
  [Allow database operations]
  ↓ False
  [Send: "⛔ Admin access only"]

Quick Reference​

NodeUse For
db.search_usersFind users by criteria, build segments
db.update_userAdd tags, update scores/metadata
db.get_userRetrieve full user data by ID

Next Steps​