k6/data

Share data efficiently between VUs using SharedArray.

The k6/data module provides utilities for efficiently sharing data between VUs.

SharedArray

SharedArray is a read-only array that is shared between all VUs. It’s useful for sharing large datasets without duplicating them in memory for each VU.

Constructor

import { SharedArray } from 'k6/data';

const data = new SharedArray('my data', function () {
  return JSON.parse(open('./data.json'));
});

name · string

Unique identifier for this shared array

callback · function

Function that returns the array data. Called only once per test run. Must be synchronous.

Usage

SharedArray instances can be accessed like regular arrays:

import { SharedArray } from 'k6/data';
import { sleep } from 'k6';

const users = new SharedArray('users', function () {
  return [
    { username: 'user1', password: 'pass1' },
    { username: 'user2', password: 'pass2' },
    { username: 'user3', password: 'pass3' },
  ];
});

export default function () {
  // Access array elements
  const user = users[0];
  console.log(user.username);

  // Get array length
  console.log(users.length);

  // Iterate over array
  users.forEach((user) => {
    console.log(user.username);
  });
}

Examples

Loading Data from JSON File

import { SharedArray } from 'k6/data';
import http from 'k6/http';

const testData = new SharedArray('test data', function () {
  return JSON.parse(open('./test-data.json'));
});

export default function () {
  const randomData = testData[Math.floor(Math.random() * testData.length)];
  http.post('https://test.k6.io/api', JSON.stringify(randomData));
}

Generating Test Data

import { SharedArray } from 'k6/data';

const data = new SharedArray('generated data', function () {
  const generated = [];
  for (let i = 0; i < 1000; i++) {
    generated.push({
      id: i,
      name: `user-${i}`,
      email: `user${i}@example.com`,
    });
  }
  return generated;
});

export default function () {
  console.log(data.length); // 1000
}

Per-VU Data Selection

import { SharedArray } from 'k6/data';
import exec from 'k6/execution';

const users = new SharedArray('all users', function () {
  return JSON.parse(open('./users.json'));
});

export default function () {
  // Each VU gets a different user based on its ID
  const vuId = exec.vu.idInInstance - 1;
  const user = users[vuId % users.length];
  console.log(`VU ${vuId} using user ${user.username}`);
}

Performance Benefits

SharedArray is designed to save memory when running tests with many VUs:

• Without SharedArray: Each VU has its own copy of the data in memory
• With SharedArray: Data is stored once and shared across all VUs

For example, with 1000 VUs and a 10MB dataset:

• Without SharedArray: ~10GB total memory usage
• With SharedArray: ~10MB total memory usage

Important Notes

SharedArray must be created in the init context (outside the default function).

The callback function must be synchronous. Async functions are not supported.

SharedArray is read-only. You cannot modify the data once created.

// ✅ Correct
import { SharedArray } from 'k6/data';

const data = new SharedArray('data', function () {
  return [1, 2, 3];
});

export default function () {
  console.log(data[0]); // OK
}

// ❌ Wrong - trying to modify
export default function () {
  data[0] = 10; // This won't work
}