> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Load Sample Dataset

Loads a hosted sample dataset, ready to upsert and query, for quickstarts, demos, and tests without generating your own vectors. The dataset is downloaded from a public S3 bucket on first use and cached on disk for later calls.

```go theme={null}
// Load a dataset by name; "" loads the default ("quickstart-75k")
func LoadSampleDataset(name string) (*SampleDataset, error)

// The same, with explicit cache control
func LoadSampleDatasetWithOptions(name string, opts LoadSampleDatasetOptions) (*SampleDataset, error)
```

### Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | `""` (`"quickstart-75k"`) | Dataset to load. `"quickstart-75k"` is currently the only one. |
| `opts.CacheDir` | `string` | `""` (`os.UserCacheDir()/cyborgdb`) | Directory for the cached dataset. |
| `opts.ForceDownload` | `bool` | `false` | Download again even if a cached copy exists. |

The functions take no `context.Context`. The download has a fixed 120-second timeout, and the decompressed dataset is capped at 512 MiB. Each dataset's SHA-256 digest is pinned in the SDK and checked after download and on every cache read, so a tampered file is rejected and downloaded again.

### Returns

`*SampleDataset`:

| Field | Type | Description |
| - | - | - |
| `Name` | `string` | Dataset identifier, e.g. `"quickstart-75k"`. |
| `Version` | `int` | Dataset schema version. |
| `Description` | `string` | Human-readable description. |
| `Dimension` | `int` | Vector dimensionality. |
| `Metric` | `string` | Distance metric the vectors were generated for. |
| `Count` | `int` | Number of items. |
| `Items` | `VectorItems` | Items with `Id`, `Vector`, and `Metadata`, ready for [`Upsert`](./encrypted-index/upsert). |
| `SampleQueries` | `[][]float32` | The first 10 query vectors. |
| `ExampleFilters` | `[]SampleFilter` | Metadata filters guaranteed to match, each with `Name`, `Filter`, and `Demonstrates`. |
| `Ids` / `Vectors` / `Metadata` | parallel slices | Raw data, aligned by position. |
| `Queries`, `MetadataQueries`, `MetadataQueryNames`, `UntrainedNeighbors`, `TrainedNeighbors`, `UntrainedMetadataMatches`, `TrainedMetadataMatches`, `UntrainedMetadataNeighbors`, `TrainedMetadataNeighbors`, `UntrainedRecall`, `TrainedRecall`, `NumUntrainedVectors`, `NumTrainedVectors` | ground truth | Fixture data for checking recall. |

### Errors

<AccordionGroup>
  <Accordion title="ErrUnknownSampleDataset">
    The dataset name is unknown.
  </Accordion>

  <Accordion title="ErrSampleDatasetDownload">
    The download returns a non-`200` status. A network failure or timeout returns the underlying error (for example a `*url.Error`) instead, without this sentinel.
  </Accordion>

  <Accordion title="ErrSampleDatasetIntegrity">
    The file fails its SHA-256 check.
  </Accordion>

  <Accordion title="ErrSampleDatasetTooLarge">
    The decompressed dataset exceeds 512 MiB.
  </Accordion>
</AccordionGroup>

These are wrapped with extra context; match them with `errors.Is`.

### Example Usage

```go theme={null}
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/cyborginc/cyborgdb-go"
)

func main() {
    ctx := context.Background()

    client, err := cyborgdb.NewClient("http://localhost:8000", "your-api-key")
    if err != nil {
        log.Fatal(err)
    }
    key, err := cyborgdb.GenerateKey()
    if err != nil {
        log.Fatal(err)
    }

    // Downloads on first use; cached afterwards
    dataset, err := cyborgdb.LoadSampleDataset("")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(dataset.Name, dataset.Count, dataset.Dimension, dataset.Metric)
    // Output: quickstart-75k 75000 128 euclidean

    dim := int32(dataset.Dimension)
    index, err := client.CreateIndex(ctx, &cyborgdb.CreateIndexParams{
        IndexName: "demo",
        IndexKey:  key,
        Dimension: &dim,
        Metric:    &dataset.Metric,
    })
    if err != nil {
        log.Fatal(err)
    }

    if err := index.Upsert(ctx, dataset.Items); err != nil {
        log.Fatal(err)
    }

    // Similarity search with a bundled query vector
    resp, err := index.Query(ctx, cyborgdb.QueryParams{QueryVector: dataset.SampleQueries[0], TopK: 5})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(len(*resp.Results.ArrayOfQueryResultItem))
    // Output: 5

    // A curated metadata filter
    example := dataset.ExampleFilters[0]
    fmt.Println(example.Name, example.Filter)
    // Output: Equality filter (string field) map[string:string_0]
    if _, err := index.Query(ctx, cyborgdb.QueryParams{QueryVector: dataset.SampleQueries[0], Filters: example.Filter}); err != nil {
        log.Fatal(err)
    }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.