Performance

Computed fields

Use the `dependencies` option instead of inline queries

A common pattern in legacy agents was to make database queries inside the get function. In the new agent, the dependencies option lets you declare which related fields you need, and the agent will fetch them automatically via JOIN, which is much faster.

Slow (inline query)
Fast (dependencies)
Best (import field)

agent.customizeCollection('post', postCollection => {
  postCollection.addField('authorFullName', {
    columnType: 'String',
    dependencies: ['authorId'],
    getValues: posts =>
      posts.map(async post => {
        // One query per post, very slow with many records
        const author = await models.authors.findOne({ where: { id: post.authorId } });
        return `${author.firstName} ${author.lastName}`;
      }),
  });
});

agent.customizeCollection('post', postCollection => {
  postCollection.addField('authorFullName', {
    columnType: 'String',
    // Agent performs a single JOIN, much faster
    dependencies: ['author:firstName', 'author:lastName'],
    getValues: posts =>
      posts.map(post => `${post.author.firstName} ${post.author.lastName}`),
  });
});

// Define the field once on the author collection
agent.customizeCollection('author', authorCollection => {
  authorCollection.addField('fullName', {
    columnType: 'String',
    dependencies: ['firstName', 'lastName'],
    getValues: authors => authors.map(a => `${a.firstName} ${a.lastName}`),
  });
});

// Import it on the post collection
agent.customizeCollection('post', postCollection => {
  postCollection.importField('authorFullName', { path: 'author:fullName' });
});

Move async calls outside the hot loop

The new agent works in batch mode. If you have external service calls (APIs, etc.), fetch all records in a single request rather than one per record:

Slow (per-record)
Fast (batch)

getValues: users =>
  users.map(async user => {
    // One API call per user
    const address = await geoWebService.getAddress(user.address_id);
    return [address.line_1, address.city].join(', ');
  }),

getValues: async users => {
  // One API call for all users
  const addresses = await geoWebService.getAddresses(users.map(u => u.address_id));
  return users.map(user => {
    const addr = addresses.find(a => a.id === user.address_id);
    return [addr.line1, addr.city].join(', ');
  });
},

Avoid duplicate queries across computed fields

If multiple computed fields depend on the same external data source, have one field fetch the data and let others depend on it:

agent.customizeCollection('users', users => {
  users.addField('userInfo', {
    columnType: { firstName: 'String', lastName: 'String' },
    dependencies: ['id'],
    getValues: async users => {
      const ids = users.map(u => u.id);
      return await authService.getUserInfo(ids); // single request
    },
  });

  users.importField('firstName', { path: 'userInfo:firstName' });
  users.importField('lastName', { path: 'userInfo:lastName' });
});

Segments

Use condition trees when possible

If your segment logic maps to a Forest condition tree, use it instead of running a raw query and filtering by IDs. The agent can push the condition tree down to the database as a native query, which is much faster.

// Fast: agent translates this to a native query
products.addSegment('InStock', () => ({
  field: 'stock_count',
  operator: 'GreaterThan',
  value: 0,
}));

// Slower: fetches all IDs first, then filters
products.addSegment('InStock', async () => {
  const ids = await db.query('SELECT id FROM products WHERE stock_count > 0');
  return { field: 'id', operator: 'In', value: ids };
});

Filtering emulation

emulateFieldFiltering and emulateFieldSorting force the agent to retrieve all records to compute values. Use them only for collections with a low number of records (a few thousand at most). Prefer replaceFieldOperator for large collections.

Overview

Agent API

Public API

CLI

Schema

Best Practices

Computed fields

Use the `dependencies` option instead of inline queries

Move async calls outside the hot loop

Avoid duplicate queries across computed fields

Segments

Use condition trees when possible

Filtering emulation

​Computed fields

​Use the dependencies option instead of inline queries

​Move async calls outside the hot loop

​Avoid duplicate queries across computed fields

​Segments

​Use condition trees when possible

​Filtering emulation

Computed fields

Use the `dependencies` option instead of inline queries

Move async calls outside the hot loop

Avoid duplicate queries across computed fields

Segments

Use condition trees when possible

Filtering emulation