shiftcraft/.claude/skills/pocketbase-best-practices/rules/query-field-selection.md

title, impact, impactDescription, tags

title	impact	impactDescription	tags
Select Only Required Fields	MEDIUM	Reduces payload size, improves response time	query, fields, performance, bandwidth

Select Only Required Fields

Use the fields parameter to request only the data you need. This reduces bandwidth and can improve query performance, especially with large text or file fields.

Incorrect (fetching everything):

// Fetching all fields when only a few are needed
const posts = await pb.collection('posts').getList(1, 20);
// Returns: id, title, content (10KB), thumbnail, author, tags, created, updated...

// Only displaying titles in a list
posts.items.forEach(post => {
  renderListItem(post.title);  // Only using title!
});
// Wasted bandwidth on content, thumbnail URLs, etc.

// Fetching user data with large profile fields
const users = await pb.collection('users').getFullList();
// Includes: avatar (file), bio (text), settings (json)...
// When you only need names for a dropdown

Correct (selecting specific fields):

// Select only needed fields
const posts = await pb.collection('posts').getList(1, 20, {
  fields: 'id,title,created'
});
// Returns only: { id, title, created }

// For a dropdown/autocomplete
const users = await pb.collection('users').getFullList({
  fields: 'id,name,avatar'
});

// Include expanded relation fields
const posts = await pb.collection('posts').getList(1, 20, {
  expand: 'author',
  fields: 'id,title,expand.author.name,expand.author.avatar'
});
// Returns: { id, title, expand: { author: { name, avatar } } }

// Wildcard for all direct fields, specific for expand
const posts = await pb.collection('posts').getList(1, 20, {
  expand: 'author,category',
  fields: '*,expand.author.name,expand.category.name'
});
// All post fields + only name from expanded relations

Using excerpt modifier:

// Get truncated text content
const posts = await pb.collection('posts').getList(1, 20, {
  fields: 'id,title,content:excerpt(200,true)'
});
// content is truncated to 200 chars with "..." appended

// Multiple excerpts
const posts = await pb.collection('posts').getList(1, 20, {
  fields: 'id,title:excerpt(50),content:excerpt(150,true)'
});

// Excerpt syntax: field:excerpt(maxLength, withEllipsis?)
// - maxLength: maximum characters
// - withEllipsis: append "..." if truncated (default: false)

Common field selection patterns:

// List view - minimal data
const listFields = 'id,title,thumbnail,author,created';

// Card view - slightly more
const cardFields = 'id,title,content:excerpt(200,true),thumbnail,author,created';

// Detail view - most fields
const detailFields = '*,expand.author.name,expand.author.avatar';

// Autocomplete - just id and display text
const autocompleteFields = 'id,name';

// Table export - specific columns
const exportFields = 'id,email,name,created,status';

// Usage
async function getPostsList() {
  return pb.collection('posts').getList(1, 20, {
    fields: listFields,
    expand: 'author'
  });
}

Performance impact:

Field Type	Impact of Selecting
text/editor	High (can be large)
file	Medium (URLs generated)
json	Medium (can be large)
relation	Low (just IDs)
number/bool	Low

Note: Field selection happens after data is fetched from database, so it primarily saves bandwidth, not database queries. For database-level optimization, ensure proper indexes.

Reference: PocketBase Fields Parameter