Skip to content

Set Operations

DBX provides comprehensive set operations through its REST API. Set operations allow you to store and manage collections of unique values, similar to Redis sets.

Overview

Set operations support storing collections of unique values under a single key, making them ideal for storing tags, user groups, unique identifiers, or any collection where duplicates are not allowed.

Endpoints

GET /redis/set/{key}

Retrieve all members from a set.

Parameters:
  • key (path) - The set key to retrieve
Response: 
{
  "members": ["user1", "user2", "user3", "user4"],
  "cardinality": 4,
  "ttl": 3600
}
Example: 
curl http://localhost:8080/redis/set/online-users

POST /redis/set/{key}

Create or update a set with multiple members.

Parameters:
  • key (path) - The set key to store
  • members (body) - Array of unique values
  • ttl (optional, body) - Time to live in seconds
Request Body: 
{
  "members": ["user1", "user2", "user3", "user4"],
  "ttl": 3600
}
Response: 
{
  "success": true,
  "key": "online-users",
  "members_count": 4
}
Example: 
curl -X POST http://localhost:8080/redis/set/online-users \
     -H "Content-Type: application/json" \
     -d '{
       "members": ["user1", "user2", "user3", "user4"],
       "ttl": 3600
     }'

DELETE /redis/set/{key}

Delete an entire set and all its members.

Parameters:
  • key (path) - The set key to delete
Response: 
{
  "success": true,
  "deleted": true
}
Example: 
curl -X DELETE http://localhost:8080/redis/set/online-users

POST /redis/set/{key}/member/{member}

Add a single member to a set.

Parameters:
  • key (path) - The set key
  • member (path) - The member to add
Response: 
{
  "success": true,
  "member": "user5",
  "added": true
}
Example: 
curl -X POST http://localhost:8080/redis/set/online-users/member/user5

DELETE /redis/set/{key}/member/{member}

Remove a single member from a set.

Parameters:
  • key (path) - The set key
  • member (path) - The member to remove
Response: 
{
  "success": true,
  "member": "user1",
  "removed": true
}
Example: 
curl -X DELETE http://localhost:8080/redis/set/online-users/member/user1

GET /redis/set/{key}/member/{member}/exists

Check if a member exists in a set.

Parameters:
  • key (path) - The set key
  • member (path) - The member to check
Response: 
{
  "exists": true
}
Example: 
curl http://localhost:8080/redis/set/online-users/member/user1/exists

GET /redis/set/{key}/cardinality

Get the number of members in a set.

Parameters:
  • key (path) - The set key
Response: 
{
  "cardinality": 4
}
Example: 
curl http://localhost:8080/redis/set/online-users/cardinality

POST /redis/set/{key}/pop

Remove and return a random member from the set.

Parameters:
  • key (path) - The set key
Response: 
{
  "success": true,
  "member": "user3"
}
Example: 
curl -X POST http://localhost:8080/redis/set/online-users/pop

Set Operations

POST /redis/set/union

Compute the union of multiple sets.

Request Body: 
{
  "keys": ["set1", "set2", "set3"]
}
Response: 
{
  "union": ["member1", "member2", "member3", "member4"],
  "cardinality": 4
}
Example: 
curl -X POST http://localhost:8080/redis/set/union \
     -H "Content-Type: application/json" \
     -d '{"keys": ["set1", "set2", "set3"]}'

POST /redis/set/intersection

Compute the intersection of multiple sets.

Request Body: 
{
  "keys": ["set1", "set2", "set3"]
}
Response: 
{
  "intersection": ["member1", "member2"],
  "cardinality": 2
}
Example: 
curl -X POST http://localhost:8080/redis/set/intersection \
     -H "Content-Type: application/json" \
     -d '{"keys": ["set1", "set2", "set3"]}'

POST /redis/set/difference

Compute the difference between sets (members in first set but not in others).

Request Body: 
{
  "keys": ["set1", "set2", "set3"]
}
Response: 
{
  "difference": ["member3"],
  "cardinality": 1
}
Example: 
curl -X POST http://localhost:8080/redis/set/difference \
     -H "Content-Type: application/json" \
     -d '{"keys": ["set1", "set2", "set3"]}'

Batch Operations

POST /redis/set/batch

Perform multiple set operations in a single request.

Request Body: 
{
  "operations": [
    {
      "type": "add",
      "key": "set1",
      "members": ["member1", "member2"]
    },
    {
      "type": "get",
      "key": "set2"
    },
    {
      "type": "addMember",
      "key": "set1",
      "member": "member3"
    }
  ]
}
Response: 
{
  "results": [
    {
      "type": "add",
      "success": true,
      "key": "set1",
      "members_count": 2
    },
    {
      "type": "get",
      "success": true,
      "members": ["member4", "member5"],
      "cardinality": 2
    },
    {
      "type": "addMember",
      "success": true,
      "member": "member3",
      "added": true
    }
  ]
}

Use Cases

1. Online Users Tracking

# Add user to online set
curl -X POST http://localhost:8080/redis/set/online-users/member/user123
 
# Check if user is online
curl http://localhost:8080/redis/set/online-users/member/user123/exists
 
# Get online user count
curl http://localhost:8080/redis/set/online-users/cardinality
 
# Remove user when they go offline
curl -X DELETE http://localhost:8080/redis/set/online-users/member/user123

2. Tag Management

# Store post tags
curl -X POST http://localhost:8080/redis/set/post:123:tags \
     -H "Content-Type: application/json" \
     -d '{
       "members": ["javascript", "nodejs", "api"],
       "ttl": 86400
     }'
 
# Add new tag
curl -X POST http://localhost:8080/redis/set/post:123:tags/member/redis
 
# Check if post has specific tag
curl http://localhost:8080/redis/set/post:123:tags/member/javascript/exists

3. Unique Collections

# Store unique IP addresses
curl -X POST http://localhost:8080/redis/set/unique-visitors \
     -H "Content-Type: application/json" \
     -d '{
       "members": ["192.168.1.100", "192.168.1.101", "10.0.0.50"],
       "ttl": 3600
     }'
 
# Add new visitor
curl -X POST http://localhost:8080/redis/set/unique-visitors/member/192.168.1.102
 
# Get unique visitor count
curl http://localhost:8080/redis/set/unique-visitors/cardinality

4. User Groups and Permissions

# Store admin users
curl -X POST http://localhost:8080/redis/set/admins \
     -H "Content-Type: application/json" \
     -d '{
       "members": ["user1", "user2", "user3"]
     }'
 
# Check if user is admin
curl http://localhost:8080/redis/set/admins/member/user1/exists
 
# Add new admin
curl -X POST http://localhost:8080/redis/set/admins/member/user4

Error Handling

All endpoints return consistent error responses:

{
  "error": "not_found",
  "message": "Set key 'online-users' not found",
  "status": 404
}

Common error types:

  • not_found - Set key doesn't exist
  • member_not_found - Member doesn't exist in set
  • invalid_key - Key format is invalid
  • invalid_member - Member format is invalid
  • duplicate_member - Member already exists in set
  • server_error - Internal server error

Performance Considerations

  1. Set Size - Large sets may impact performance for operations like GET
  2. Member Uniqueness - DBX automatically handles duplicates
  3. Batch Operations - Use batch endpoints for multiple operations
  4. TTL Management - Set appropriate TTL values for set expiration

Data Types

Set members support various data types:

  • Strings - Most common, stored as-is
  • Numbers - Stored as strings, can be parsed by client
  • UUIDs - Stored as strings
  • JSON - Stored as stringified JSON (not recommended for sets)

Rate Limits

Set operations are subject to the same rate limiting as other API endpoints:

  • Default: 100 requests per minute per IP
  • Configurable via environment variables