WebSocket Hash Operations

The DBX WebSocket API provides real-time hash operations for Redis. This guide covers all available hash methods and their usage patterns.

Installation

npm install @0dbx/redis

Basic Usage

import { DbxWsClient } from "@0dbx/redis";
 
// Create WebSocket client
const wsClient = new DbxWsClient("ws://localhost:3000/redis_ws");
 
// Hash operations
await wsClient.hash.setField("user:1", "name", "John Doe");
const name = await wsClient.hash.getField("user:1", "name");

Connection Setup

Before using hash operations, establish a WebSocket connection:

import { DBXWebSocketClient } from "@effortlesslabs/dbx";
 
const client = new DBXWebSocketClient({
  url: "ws://localhost:8080/ws",
  token: "your-jwt-token",
});
 
await client.connect();

Hash Operations

HSET - Set Hash Field

Set a field in a hash to a value.

Request:

{
  "id": "req-1",
  "method": "HSET",
  "params": {
    "key": "user:123",
    "field": "name",
    "value": "John Doe"
  }
}

Response:

{
  "id": "req-1",
  "result": {
    "success": true,
    "created": true
  }
}

HMSET - Set Multiple Hash Fields

Set multiple fields in a hash atomically.

Request:

{
  "id": "req-2",
  "method": "HMSET",
  "params": {
    "key": "user:123",
    "fields": {
      "name": "John Doe",
      "email": "john@example.com",
      "age": "30",
      "city": "New York"
    }
  }
}

Response:

{
  "id": "req-2",
  "result": {
    "success": true
  }
}

HGET - Get Hash Field

Get the value of a field in a hash.

Request:

{
  "id": "req-3",
  "method": "HGET",
  "params": {
    "key": "user:123",
    "field": "name"
  }
}

Response:

{
  "id": "req-3",
  "result": {
    "value": "John Doe"
  }
}

Error Response:

{
  "id": "req-3",
  "error": {
    "code": "FIELD_NOT_FOUND",
    "message": "Field 'name' not found in hash 'user:123'"
  }
}

HMGET - Get Multiple Hash Fields

Get multiple field values from a hash.

Request:

{
  "id": "req-4",
  "method": "HMGET",
  "params": {
    "key": "user:123",
    "fields": ["name", "email", "age"]
  }
}

Response:

{
  "id": "req-4",
  "result": {
    "values": ["John Doe", "john@example.com", "30"]
  }
}

HGETALL - Get All Hash Fields

Get all fields and values from a hash.

Request:

{
  "id": "req-5",
  "method": "HGETALL",
  "params": {
    "key": "user:123"
  }
}

Response:

{
  "id": "req-5",
  "result": {
    "fields": {
      "name": "John Doe",
      "email": "john@example.com",
      "age": "30",
      "city": "New York"
    }
  }
}

HDEL - Delete Hash Fields

Delete one or more fields from a hash.

Request:

{
  "id": "req-6",
  "method": "HDEL",
  "params": {
    "key": "user:123",
    "fields": ["age", "city"]
  }
}

Response:

{
  "id": "req-6",
  "result": {
    "deleted": 2
  }
}

HEXISTS - Check Field Exists

Check if a field exists in a hash.

Request:

{
  "id": "req-7",
  "method": "HEXISTS",
  "params": {
    "key": "user:123",
    "field": "name"
  }
}

Response:

{
  "id": "req-7",
  "result": {
    "exists": true
  }
}

HKEYS - Get Hash Field Names

Get all field names in a hash.

Request:

{
  "id": "req-8",
  "method": "HKEYS",
  "params": {
    "key": "user:123"
  }
}

Response:

{
  "id": "req-8",
  "result": {
    "keys": ["name", "email", "age", "city"]
  }
}

HVALS - Get Hash Values

Get all values in a hash.

Request:

{
  "id": "req-9",
  "method": "HVALS",
  "params": {
    "key": "user:123"
  }
}

Response:

{
  "id": "req-9",
  "result": {
    "values": ["John Doe", "john@example.com", "30", "New York"]
  }
}

HLEN - Get Hash Length

Get the number of fields in a hash.

Request:

{
  "id": "req-10",
  "method": "HLEN",
  "params": {
    "key": "user:123"
  }
}

Response:

{
  "id": "req-10",
  "result": {
    "length": 4
  }
}

HINCRBY - Increment Hash Field

Increment a numeric field in a hash by a specified amount.

Request:

{
  "id": "req-11",
  "method": "HINCRBY",
  "params": {
    "key": "user:123",
    "field": "visits",
    "amount": 1
  }
}

Response:

{
  "id": "req-11",
  "result": {
    "value": 42
  }
}

HINCRBYFLOAT - Increment Hash Field by Float

Increment a numeric field in a hash by a floating-point amount.

Request:

{
  "id": "req-12",
  "method": "HINCRBYFLOAT",
  "params": {
    "key": "user:123",
    "field": "score",
    "amount": 0.5
  }
}

Response:

{
  "id": "req-12",
  "result": {
    "value": 95.5
  }
}

HSETNX - Set Hash Field if Not Exists

Set a field in a hash only if it doesn't already exist.

Request:

{
  "id": "req-13",
  "method": "HSETNX",
  "params": {
    "key": "user:123",
    "field": "created_at",
    "value": "2024-01-15T10:30:00Z"
  }
}

Response:

{
  "id": "req-13",
  "result": {
    "success": true,
    "created": true
  }
}

HSTRLEN - Get Hash Field String Length

Get the length of a string field in a hash.

Request:

{
  "id": "req-14",
  "method": "HSTRLEN",
  "params": {
    "key": "user:123",
    "field": "name"
  }
}

Response:

{
  "id": "req-14",
  "result": {
    "length": 8
  }
}

HRANDFIELD - Get Random Hash Field

Get a random field from a hash.

Request:

{
  "id": "req-15",
  "method": "HRANDFIELD",
  "params": {
    "key": "user:123",
    "count": 2,
    "with_values": true
  }
}

Response:

{
  "id": "req-15",
  "result": {
    "fields": [
      { "field": "name", "value": "John Doe" },
      { "field": "email", "value": "john@example.com" }
    ]
  }
}

Error Handling

All WebSocket hash operations return standardized error responses:

{
  "id": "request-id",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  }
}

Common error codes:

KEY_NOT_FOUND: The specified hash key doesn't exist
FIELD_NOT_FOUND: The specified field doesn't exist in the hash
TYPE_MISMATCH: The key exists but is not a hash type
INVALID_VALUE: The value is not valid for the operation
AUTHENTICATION_FAILED: Invalid or missing authentication token
RATE_LIMITED: Request rate limit exceeded

TypeScript SDK Example

import { DbxWsClient } from "@0dbx/redis";
 
const wsClient = new DbxWsClient("ws://localhost:3000/redis_ws");
 
// Hash operations
await wsClient.hash.setField("user:1", "name", "John Doe");
await wsClient.hash.setField("user:1", "email", "john@example.com");
const name = await wsClient.hash.getField("user:1", "name");
console.log(name); // "John Doe"

Best Practices

Field Naming: Use descriptive field names that clearly indicate the data they contain
Data Types: Be consistent with data types across your application
Batch Operations: Use HMSET/HMGET for multiple operations when possible
Memory Usage: Be mindful of hash size as all fields are loaded into memory
Key Expiration: Set appropriate TTL on hash keys for temporary data
Field Validation: Validate field values before storing them

Performance Considerations

Hash operations are generally faster than string operations for structured data
HMSET/HMGET are more efficient than multiple individual HSET/HGET calls
HGETALL can be expensive for large hashes - consider using HKEYS or HMGET for specific fields
Hash operations are atomic, making them suitable for concurrent access patterns
Consider using hash partitioning for very large datasets