Class: CardDB::Resources::Records

Inherits:
Base
  • Object
show all
Includes:
FilterOperators
Defined in:
lib/carddb/resources/records.rb

Overview

Records resource for searching and fetching records

Instance Attribute Summary

Attributes inherited from Base

#client, #config, #connection

Instance Method Summary collapse

Methods included from FilterOperators

#contains, #eq, #gt, #gte, #ilike, #is_not_null, #is_null, #like, #lt, #lte, #neq, #not_within, #within

Methods inherited from Base

#initialize

Constructor Details

This class inherits a constructor from CardDB::Resources::Base

Instance Method Details

#fetch(id, cache: nil, include_pricing: false) ⇒ Record?

Fetch a single record by ID

Parameters:

  • id (String) —

    The record UUID

  • cache (Boolean, nil) (defaults to: nil) —

    Whether to cache (nil = use config setting)

  • include_pricing (Boolean) (defaults to: false) —

    Include live TCGPlayer pricing when configured

Returns:

  • (Record, nil) —

    The record or nil if not found



128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/carddb/resources/records.rb', line 128

def fetch(id, cache: nil, include_pricing: false)
  key = cache_key('records', 'fetch', id: id, include_pricing: include_pricing)
  with_cache(key, resource: :records, cache: cache) do
    query = QueryBuilder.fetch_record(include_pricing: include_pricing)
    data = connection.execute(query, { id: id })

    return nil unless data['fetchRecord']

    Record.new(data['fetchRecord'], client: client)
  end
end

#fetch_many(ids, include_pricing: false) ⇒ Array<Record>

Fetch multiple records by IDs

Parameters:

  • ids (Array<String>) —

    Array of record UUIDs (max 1000)

  • include_pricing (Boolean) (defaults to: false) —

    Include live TCGPlayer pricing when configured

Returns:

  • (Array<Record>) —

    Array of records

Raises:

  • (ArgumentError) —

    If more than 1000 IDs provided



253
254
255
256
257
258
259
260
 
# File 'lib/carddb/resources/records.rb', line 253

def fetch_many(ids, include_pricing: false)
  raise ArgumentError, 'Maximum 1000 IDs allowed' if ids.length > 1000

  query = QueryBuilder.fetch_records(include_pricing: include_pricing)
  data = connection.execute(query, { ids: ids })

  (data['fetchRecords'] || []).map { |r| Record.new(r, client: client) }
end

#get(identifier:, dataset_key:, publisher_slug: nil, game_key: nil, cache: nil, include_pricing: false) ⇒ Record?

Get a record by its identifier value

Looks up the record using the dataset’s designated identifier field. Returns nil if the dataset has no identifier field or if no matching record is found.

Examples:

record = client.records.get(identifier: "xy1-1", dataset_key: "cards")

Parameters:

  • identifier (String) —

    The identifier value to look up

  • dataset_key (String) —

    Dataset key (required)

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

    Publisher slug (uses default if not provided)

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

    Game key (uses default if not provided)

  • cache (Boolean, nil) (defaults to: nil) —

    Whether to cache (nil = use config setting)

  • include_pricing (Boolean) (defaults to: false) —

    Include live TCGPlayer pricing when configured

Returns:

  • (Record, nil) —

    The record or nil if not found



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/carddb/resources/records.rb', line 155

def get(
  identifier:,
  dataset_key:,
  publisher_slug: nil,
  game_key: nil,
  cache: nil,
  include_pricing: false
)
  resolved_publisher = resolve_publisher(publisher_slug)
  resolved_game = resolve_game(game_key)

  validate_access!(resolved_publisher, resolved_game)

  key = cache_key('records', 'get', publisher_slug: resolved_publisher, game_key: resolved_game,
                                    dataset_key: dataset_key, identifier: identifier,
                                    include_pricing: include_pricing)
  with_cache(key, resource: :records, cache: cache) do
    query = QueryBuilder.fetch_record_by_identifier(include_pricing: include_pricing)
    variables = {
      publisherSlug: resolved_publisher,
      gameKey: resolved_game,
      datasetKey: dataset_key,
      identifier: identifier
    }

    data = connection.execute(query, variables)

    return nil unless data['fetchRecordByIdentifier']

    Record.new(data['fetchRecordByIdentifier'], client: client)
  end
end

#get_many(identifiers:, dataset_key:, publisher_slug: nil, game_key: nil, cache: nil, include_pricing: false) ⇒ Array<Record>

Get multiple records by their identifier values

Looks up records using the dataset’s designated identifier field. Missing identifiers are omitted from the result.

Examples:

records = client.records.get_many(
  identifiers: ["xy1-1", "xy1-2"],
  dataset_key: "cards"
)

Parameters:

  • identifiers (Array<String>) —

    Identifier values to look up (max 1000)

  • dataset_key (String) —

    Dataset key (required)

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

    Publisher slug (uses default if not provided)

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

    Game key (uses default if not provided)

  • cache (Boolean, nil) (defaults to: nil) —

    Whether to cache (nil = use config setting)

  • include_pricing (Boolean) (defaults to: false) —

    Include live TCGPlayer pricing when configured

Returns:

  • (Array<Record>) —

    Matching records

Raises:

  • (ArgumentError) —

    If more than 1000 identifiers are provided



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/carddb/resources/records.rb', line 207

def get_many(
  identifiers:,
  dataset_key:,
  publisher_slug: nil,
  game_key: nil,
  cache: nil,
  include_pricing: false
)
  raise ArgumentError, 'Maximum 1000 identifiers allowed' if identifiers.length > 1000
  return [] if identifiers.empty?

  resolved_publisher = resolve_publisher(publisher_slug)
  resolved_game = resolve_game(game_key)

  validate_access!(resolved_publisher, resolved_game)

  key = cache_key(
    'records',
    'get_many',
    publisher_slug: resolved_publisher,
    game_key: resolved_game,
    dataset_key: dataset_key,
    identifiers: identifiers,
    include_pricing: include_pricing
  )
  with_cache(key, resource: :records, cache: cache) do
    query = QueryBuilder.fetch_records_by_identifier(include_pricing: include_pricing)
    variables = {
      publisherSlug: resolved_publisher,
      gameKey: resolved_game,
      datasetKey: dataset_key,
      identifiers: identifiers
    }

    data = connection.execute(query, variables)

    (data['fetchRecordsByIdentifier'] || []).map { |record| Record.new(record, client: client) }
  end
end

#search(dataset_key:, publisher_slug: nil, game_key: nil, filter: nil, search: nil, order_by: nil, resolve_links: nil, first: nil, after: nil, validate_schema: nil, include_pricing: false) {|FilterBuilder| ... } ⇒ Collection<Record>

Search for records in a dataset

rubocop:disable Metrics/MethodLength, Metrics/ParameterLists

Examples:

Basic search

records = client.records.search(dataset_key: "cards")

With filter DSL

records = client.records.search(dataset_key: "cards") do
  where(type: "creature")
  where(hp: gte(100))
end

With hash filter

records = client.records.search(
  dataset_key: "cards",
  filter: { "type" => "creature" }
)

Parameters:

  • dataset_key (String) —

    Dataset key (required)

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

    Publisher slug (uses default if not provided)

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

    Game key (uses default if not provided)

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

    Filter conditions

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

    Full-text search

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

    Field to order by (e.g., “name:asc”)

  • resolve_links (Array<String>, nil) (defaults to: nil) —

    Link fields to resolve

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

    Maximum number of results

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

    Cursor for pagination

  • validate_schema (Boolean, nil) (defaults to: nil) —

    Whether to validate against schema

  • include_pricing (Boolean) (defaults to: false) —

    Include live TCGPlayer pricing when configured

Yields:

Returns:



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/carddb/resources/records.rb', line 40

def search(
  dataset_key:,
  publisher_slug: nil,
  game_key: nil,
  filter: nil,
  search: nil,
  order_by: nil,
  resolve_links: nil,
  first: nil,
  after: nil,
  validate_schema: nil,
  include_pricing: false,
  &block
)
  resolved_publisher = resolve_publisher(publisher_slug)
  resolved_game = resolve_game(game_key)

  validate_access!(resolved_publisher, resolved_game)

  # Build filter from DSL block if provided
  final_filter = if block_given?
                   FilterBuilder.build(&block)
                 else
                   filter
                 end

  query = QueryBuilder.search_records(
    publisher_slug: resolved_publisher,
    game_key: resolved_game,
    dataset_key: dataset_key,
    filter: final_filter,
    search: search,
    order_by: order_by,
    resolve_links: resolve_links,
    first: first,
    after: after,
    validate_schema: validate_schema,
    include_pricing: include_pricing
  )

  variables = build_variables(
    publisherSlug: resolved_publisher,
    gameKey: resolved_game,
    datasetKey: dataset_key,
    filter: final_filter,
    search: search,
    orderBy: order_by,
    resolveLinks: resolve_links,
    first: first,
    after: after,
    validateSchema: validate_schema
  )

  data = connection.execute(query, variables)

  # Create next page loader that preserves the filter block
  search_params = {
    dataset_key: dataset_key,
    publisher_slug: publisher_slug,
    game_key: game_key,
    filter: final_filter,
    search: search,
    order_by: order_by,
    resolve_links: resolve_links,
    first: first,
    validate_schema: validate_schema,
    include_pricing: include_pricing
  }

  next_page_loader = lambda do |cursor|
    search(**search_params, after: cursor)
  end

  Collection.new(
    data['searchRecords'],
    item_class: Record,
    next_page_loader: next_page_loader,
    client: client
  )
end