# `createDataStream`

The `createDataStream` function allows you to stream additional data to the client (see [Streaming Data](/docs/ai-sdk-ui/streaming-data)).

## Import

<Snippet text={`import { createDataStream } from "ai"`} prompt={false} />

## Example

```tsx
const stream = createDataStream({
  async execute(dataStream) {
    // Write data
    dataStream.writeData({ value: 'Hello' });

    // Write annotation
    dataStream.writeMessageAnnotation({ type: 'status', value: 'processing' });

    // Merge another stream
    const otherStream = getAnotherStream();
    dataStream.merge(otherStream);
  },
  onError: error => `Custom error: ${error.message}`,
});
```

## API Signature

### Parameters

<PropertiesTable
  content={[
    {
      name: 'execute',
      type: '(dataStream: DataStreamWriter) => Promise<void> | void',
      description:
        'A function that receives a DataStreamWriter instance and can use it to write data to the stream.',
      properties: [
        {
          type: 'DataStreamWriter',
          parameters: [
            {
              name: 'write',
              type: '(data: DataStreamString) => void',
              description: 'Appends a data part to the stream.',
            },
            {
              name: 'writeData',
              type: '(value: JSONValue) => void',
              description: 'Appends a data part to the stream.',
            },
            {
              name: 'writeMessageAnnotation',
              type: '(value: JSONValue) => void',
              description: 'Appends a message annotation to the stream.',
            },
            {
              name: 'writeSource',
              type: '(source: Source) => void',
              description: 'Appends a source part to the stream.',
            },
            {
              name: 'merge',
              type: '(stream: ReadableStream<DataStreamString>) => void',
              description:
                'Merges the contents of another stream to this stream.',
            },
            {
              name: 'onError',
              type: '((error: unknown) => string) | undefined',
              description:
                'Error handler that is used by the data stream writer. This is intended for forwarding when merging streams to prevent duplicated error masking.',
            },
          ],
        },
      ],
    },
    {
      name: 'onError',
      type: '(error: unknown) => string',
      description:
        'A function that handles errors and returns an error message string. By default, it returns "An error occurred."',
    },
  ]}
/>

### Returns

`ReadableStream<DataStreamString>`

A readable stream that emits formatted data stream parts.


## Navigation

- [useChat](/v4/docs/reference/ai-sdk-ui/use-chat)
- [useCompletion](/v4/docs/reference/ai-sdk-ui/use-completion)
- [useObject](/v4/docs/reference/ai-sdk-ui/use-object)
- [useAssistant](/v4/docs/reference/ai-sdk-ui/use-assistant)
- [AssistantResponse](/v4/docs/reference/ai-sdk-ui/assistant-response)
- [convertToCoreMessages](/v4/docs/reference/ai-sdk-ui/convert-to-core-messages)
- [appendResponseMessages](/v4/docs/reference/ai-sdk-ui/append-response-messages)
- [appendClientMessage](/v4/docs/reference/ai-sdk-ui/append-client-message)
- [createDataStream](/v4/docs/reference/ai-sdk-ui/create-data-stream)
- [createDataStreamResponse](/v4/docs/reference/ai-sdk-ui/create-data-stream-response)
- [pipeDataStreamToResponse](/v4/docs/reference/ai-sdk-ui/pipe-data-stream-to-response)
- [StreamData](/v4/docs/reference/ai-sdk-ui/stream-data)


[Full Sitemap](/sitemap.md)