Projections with _fields

PulsePI allows clients to request only specific fields from the database by using the _fields key inside the params object.

How _fields Works

_fields is an array of strings
Each string is a field name you want in the response
Any field not included will be excluded from the result

Single Request with Projection

Request Example

json

{
  "module": "user",
  "action": "list",
  "params": {
    "_fields": ["name", "email"]
  }
}

➡️ Will return only name and email fields for all users.

Response Example

json

{
  "status": "success",
  "data": [
    {
      "name": "John Doe",
      "email": "john@example.com"
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com"
    }
  ],
  "meta": {
    "executedAt": "2025-04-17T15:15:00.000Z"
  }
}

Batch Request with Projection

Request Example

json

{
  "module": ["user", "posts"],
  "action": ["list", "getPosts"],
  "params": [
    { "_fields": ["name"] },
    { "_fields": ["title", "content"] }
  ]
}

➡️ Returns:

For user.list → only name
For posts.getPosts → only title and content

Response Example

json

{
  "status": "multi-success",
  "count": 2,
  "results": [
    {
      "module": "user",
      "action": "list",
      "status": "success",
      "data": [
        { "name": "John Doe" },
        { "name": "Jane Smith" }
      ]
    },
    {
      "module": "posts",
      "action": "getPosts",
      "status": "success",
      "data": [
        {
          "title": "Post One",
          "content": "This is the content of Post One."
        },
        {
          "title": "Post Two",
          "content": "This is the content of Post Two."
        }
      ]
    }
  ],
  "meta": {
    "executedAt": "2025-04-17T15:30:00.000Z"
  }
}

Best Practices

Only request the fields you actually need to minimize response size
For nested objects, use dot notation (e.g., ["user.name", "user.email"])
Always include ID fields if you need to reference the objects later