Class: Braintrust::API::Datasets

Inherits:
Object
  • Object
show all
Defined in:
lib/braintrust/api/datasets.rb

Overview

Datasets API namespace Provides methods for creating, fetching, and querying datasets

Instance Method Summary collapse

Constructor Details

#initialize(api) ⇒ Datasets

Returns a new instance of Datasets.



14
15
16
17
 
# File 'lib/braintrust/api/datasets.rb', line 14

def initialize(api)
  @api = api
  @state = api.state
end

Instance Method Details

#create(name:, project_name: nil, project_id: nil, description: nil, metadata: nil) ⇒ Hash

Create or register a dataset (idempotent) Uses app API /api/dataset/register which is idempotent - calling this method multiple times with the same name will return the existing dataset.

Parameters:

  • project_name (String, nil) (defaults to: nil) —

    Project name

  • project_id (String, nil) (defaults to: nil) —

    Project ID

  • name (String) —

    Dataset name

  • description (String, nil) (defaults to: nil) —

    Optional description

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata

Returns:

  • (Hash) —

    Response with “project”, “dataset”, and optional “found_existing” keys. The “found_existing” field is true if the dataset already existed, false/nil if newly created.



66
67
68
69
70
71
72
73
74
 
# File 'lib/braintrust/api/datasets.rb', line 66

def create(name:, project_name: nil, project_id: nil, description: nil, metadata: nil)
  payload = {dataset_name: name, org_id: @state.org_id}
  payload[:project_name] = project_name if project_name
  payload[:project_id] = project_id if project_id
  payload[:description] = description if description
  payload[:metadata] = metadata if metadata

  http_post_json_app("/api/dataset/register", payload)
end

#delete(id:) ⇒ Hash

Delete a dataset by ID DELETE /v1/dataset/id

Parameters:

  • id (String) —

    Dataset UUID

Returns:

  • (Hash) —

    Delete response



89
90
91
 
# File 'lib/braintrust/api/datasets.rb', line 89

def delete(id:)
  http_request(:delete, "/v1/dataset/#{id}")
end

#fetch(id:, limit: 1000, cursor: nil, version: nil) ⇒ Hash

Fetch records from dataset using BTQL POST /btql

Parameters:

  • id (String) —

    Dataset UUID

  • limit (Integer) (defaults to: 1000) —

    Max records per page (default: 1000)

  • cursor (String, nil) (defaults to: nil) —

    Pagination cursor

  • version (String, nil) (defaults to: nil) —

    Dataset version

Returns:

  • (Hash) —

    Hash with :records array and :cursor string



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/braintrust/api/datasets.rb', line 107

def fetch(id:, limit: 1000, cursor: nil, version: nil)
  query = {
    from: {
      op: "function",
      name: {op: "ident", name: ["dataset"]},
      args: [{op: "literal", value: id}]
    },
    select: [{op: "star"}],
    limit: limit
  }
  query[:cursor] = cursor if cursor

  payload = {query: query, fmt: "jsonl"}
  payload[:version] = version if version

  response = http_post_json_raw("/btql", payload)
  Braintrust::Internal::Http.decompress_response!(response)

  # Parse JSONL response
  records = response.body.lines
    .map { |line| JSON.parse(line.strip) if line.strip.length > 0 }
    .compact

  # Extract pagination cursor from headers
  next_cursor = response["x-bt-cursor"] || response["x-amz-meta-bt-cursor"]

  {records: records, cursor: next_cursor}
end

#get(project_name:, name:) ⇒ Hash

Fetch exactly one dataset by project + name (convenience method)

Parameters:

  • project_name (String) —

    Project name

  • name (String) —

    Dataset name

Returns:

  • (Hash) —

    Dataset metadata

Raises:



41
42
43
44
45
46
 
# File 'lib/braintrust/api/datasets.rb', line 41

def get(project_name:, name:)
  result = list(project_name: project_name, dataset_name: name)
  metadata = result["objects"]&.first
  raise Error, "Dataset '#{name}' not found in project '#{project_name}'" unless metadata
  metadata
end

#get_by_id(id:) ⇒ Hash

Fetch dataset metadata by ID GET /v1/dataset/id

Parameters:

  • id (String) —

    Dataset UUID

Returns:

  • (Hash) —

    Dataset metadata



52
53
54
 
# File 'lib/braintrust/api/datasets.rb', line 52

def get_by_id(id:)
  http_get("/v1/dataset/#{id}")
end

#insert(id:, events:) ⇒ Hash

Insert events into a dataset POST /v1/dataset/id/insert

Parameters:

  • id (String) —

    Dataset UUID

  • events (Array<Hash>) —

    Array of event records

Returns:

  • (Hash) —

    Insert response



81
82
83
 
# File 'lib/braintrust/api/datasets.rb', line 81

def insert(id:, events:)
  http_post_json("/v1/dataset/#{id}/insert", {events: events})
end

#list(project_name: nil, dataset_name: nil, project_id: nil, limit: nil) ⇒ Hash

List datasets with optional filters GET /v1/dataset?project_name=X&dataset_name=Y&…

Parameters:

  • project_name (String, nil) (defaults to: nil) —

    Filter by project name

  • dataset_name (String, nil) (defaults to: nil) —

    Filter by dataset name

  • project_id (String, nil) (defaults to: nil) —

    Filter by project ID

  • limit (Integer, nil) (defaults to: nil) —

    Limit number of results

Returns:

  • (Hash) —

    Response with “objects” array



26
27
28
29
30
31
32
33
34
 
# File 'lib/braintrust/api/datasets.rb', line 26

def list(project_name: nil, dataset_name: nil, project_id: nil, limit: nil)
  params = {}
  params["project_name"] = project_name if project_name
  params["dataset_name"] = dataset_name if dataset_name
  params["project_id"] = project_id if project_id
  params["limit"] = limit if limit

  http_get("/v1/dataset", params)
end

#permalink(id:) ⇒ String

Generate a permalink URL to view a dataset in the Braintrust UI

Parameters:

  • id (String) —

    Dataset UUID

Returns:

  • (String) —

    Permalink URL



96
97
98
 
# File 'lib/braintrust/api/datasets.rb', line 96

def permalink(id:)
  @state.object_permalink(object_type: "dataset", object_id: id)
end