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) ⇒ 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)

Returns:

  • (Record, nil) —

    The record or nil if not found



123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/carddb/resources/records.rb', line 123

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

    return nil unless data['fetchRecord']

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

#fetch_many(ids) ⇒ Array<Record>

Fetch multiple records by IDs

Parameters:

  • ids (Array<String>) —

    Array of record UUIDs (max 1000)

Returns:

  • (Array<Record>) —

    Array of records

Raises:

  • (ArgumentError) —

    If more than 1000 IDs provided



229
230
231
232
233
234
235
236
 
# File 'lib/carddb/resources/records.rb', line 229

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

  query = QueryBuilder.fetch_records
  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) ⇒ 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)

Returns:

  • (Record, nil) —

    The record or nil if not found



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/carddb/resources/records.rb', line 149

def get(identifier:, dataset_key:, publisher_slug: nil, game_key: nil, cache: nil)
  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)
  with_cache(key, resource: :records, cache: cache) do
    query = QueryBuilder.fetch_record_by_identifier
    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) ⇒ 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)

Returns:

  • (Array<Record>) —

    Matching records

Raises:

  • (ArgumentError) —

    If more than 1000 identifiers are provided



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/carddb/resources/records.rb', line 192

def get_many(identifiers:, dataset_key:, publisher_slug: nil, game_key: nil, cache: nil)
  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
  )
  with_cache(key, resource: :records, cache: cache) do
    query = QueryBuilder.fetch_records_by_identifier
    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) {|FilterBuilder| ... } ⇒ Collection<Record>

Search for records in a dataset

rubocop:disable Metrics/MethodLength

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

Yields:

Returns:



39
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
 
# File 'lib/carddb/resources/records.rb', line 39

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,
  &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
  )

  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
  }

  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