# Stream metadata

Every stream in EventStoreDB has metadata stream associated with it, prefixed by $$, so the metadata stream from a stream called foo is $$foo. Internally, the metadata includes information such as the ACL of the stream, the maximum count and age for the events in the stream. Client code can also add information into stream metadata for use with projections or the client API.

Stream metadata is stored internally as JSON, and you can access it over the HTTP API.

# Reading stream metadata

To read the metadata, issue a GET request to the attached metadata resource, which is typically of the form:

http://{eventstore-ip-address}/streams/{stream-name}/metadata

You should not access metadata by constructing this URL yourself, as the right to change the resource address is reserved. Instead, you should follow the link from the stream itself, which enables your client to tolerate future changes to the addressing structure.

::: el-tab label="Request" <<< @/docs/server/5.0.8/http-api/sample-code/read-metadata.sh#curl ::: ::: el-tab label="Response" <<< @/docs/server/5.0.8/http-api/sample-code/read-metadata.sh#response :::

Once you have the URI of the metadata stream, issue a GET request to retrieve the metadata:

If you have security enabled, reading metadata may require that you pass credentials, as in the examples above. If credentials are required and you do not pass them, then you receive a 401 Unauthorized response.

::: el-tab label="Request" <<< @/docs/server/5.0.8/http-api/sample-code/missing-credentials.sh#curl ::: ::: el-tab label="Response" <<< @/docs/server/5.0.8/http-api/sample-code/missing-credentials.sh#response :::

# Writing metadata

To update the metadata for a stream, issue a POST request to the metadata resource.

Inside a file named metadata.json:

[
    {
        "eventId": "7c314750-05e1-439f-b2eb-f5b0e019be72",
        "eventType": "$user-updated",
        "data": {
            "readRole": "$all",
            "metaReadRole": "$all"
        }
    }
]

You can also add user-specified metadata here. Some examples user-specified metadata are:

  • Which adapter populates a stream.
  • Which projection created a stream.
  • A correlation ID to a business process.

You then post this information is then posted to the stream:

::: el-tab label="Request" <<< @/docs/server/5.0.8/http-api/sample-code/update-metadata.sh#curl ::: ::: el-tab label="Response" <<< @/docs/server/5.0.8/http-api/sample-code/update-metadata.sh#response :::

If the specified user does not have permissions to write to the stream metadata, you receive a '401 Unauthorized' response.

Last Updated: 10/12/2020, 9:42:14 PM