Module: AnkiConnect::Client::Notes

Included in:
AnkiConnect::Client
Defined in:
lib/anki_connect/notes.rb

Overview

Methods to create, update, query, and manage notes (which generate cards).

Instance Method Summary collapse

Instance Method Details

#add_note(deck_name:, note_type_name:, fields:, tags: [], media: nil, options: nil) ⇒ Integer

Creates a new note.

Parameters:

  • deck_name (String) —

    Target deck

  • note_type_name (String) —

    Note type

  • fields (Hash) —

    Field names to values

  • tags (Array<String>) (defaults to: []) —

    Tags (optional)

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

    Media to add (audio:, video:, picture: arrays)

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

    Options such as allow_duplicate and duplicate_scope

Returns:

  • (Integer) —

    Note ID on success



16
17
18
19
20
21
 
# File 'lib/anki_connect/notes.rb', line 16

def add_note(deck_name:, note_type_name:, fields:, tags: [], media: nil, options: nil)
  note = { deck_name: deck_name, note_type_name: note_type_name, fields: fields, tags: tags }
  note[:media] = media unless media.nil?
  note[:options] = options unless options.nil?
  request(:addNote, note: normalize_note(note))
end

#add_notes(notes) ⇒ Array<Integer>

Creates multiple notes.

The operation is all-or-nothing; AnkiConnect rolls back all additions if any note fails.

Parameters:

  • notes (Array<Hash>) —

    Array of note hashes (same keys as add_note)

Returns:

  • (Array<Integer>) —

    Array of note IDs



29
30
31
 
# File 'lib/anki_connect/notes.rb', line 29

def add_notes(notes)
  request(:addNotes, notes: notes.map { |note| normalize_note(note) })
end

#add_tags(note_ids, tags) ⇒ nil

Adds tags to notes.

Parameters:

  • note_ids (Array<Integer>) —

    Array of note IDs

  • tags (String, Array<String>) —

    Tag(s) to add

Returns:

  • (nil) 


131
132
133
 
# File 'lib/anki_connect/notes.rb', line 131

def add_tags(note_ids, tags)
  request(:addTags, notes: note_ids, tags: normalize_tag_query(tags))
end

#change_note_type(id, note_type_name:, fields:, tags:) ⇒ nil

Changes a note's note type.

All fields not supplied are cleared when the note type changes.

Parameters:

  • id (Integer) —

    Note ID

  • note_type_name (String) —

    New note type name

  • fields (Hash) —

    Complete values for fields in the new note type

  • tags (Array<String>) —

    Replacement tags

Returns:

  • (nil) 


114
115
116
 
# File 'lib/anki_connect/notes.rb', line 114

def change_note_type(id, note_type_name:, fields:, tags:)
  request(:updateNoteModel, note: { id: id, modelName: note_type_name, fields: fields, tags: tags })
end

#clear_unused_tags ⇒ nil

Removes unused tags from collection.

Returns:

  • (nil) 


154
155
156
 
# File 'lib/anki_connect/notes.rb', line 154

def clear_unused_tags
  request(:clearUnusedTags)
end

#delete_notes(note_ids) ⇒ nil

Deletes notes and all associated cards.

Parameters:

  • note_ids (Array<Integer>) —

    Array of note IDs

Returns:

  • (nil) 


206
207
208
 
# File 'lib/anki_connect/notes.rb', line 206

def delete_notes(note_ids)
  request(:deleteNotes, notes: note_ids)
end

#note_addability(note) ⇒ Hash

Gets addability details for one note.

Parameters:

  • note (Hash) —

    Candidate note

Returns:

  • (Hash) —

    Hash with canAdd and optional error



45
46
47
 
# File 'lib/anki_connect/notes.rb', line 45

def note_addability(note)
  request(:canAddNoteWithErrorDetail, note: normalize_note(note))
end

#note_addability_details(notes) ⇒ Array<Hash>

Gets addability details for each note, preserving input order.

Parameters:

  • notes (Array<Hash>) —

    Candidate notes

Returns:

  • (Array<Hash>) —

    Hashes with canAdd and optional error



61
62
63
 
# File 'lib/anki_connect/notes.rb', line 61

def note_addability_details(notes)
  request(:canAddNotesWithErrorDetail, notes: notes.map { |note| normalize_note(note) })
end

#note_addability_statuses(notes) ⇒ Array<Boolean>

Gets addability status for each note, preserving input order.

Parameters:

  • notes (Array<Hash>) —

    Candidate notes

Returns:

  • (Array<Boolean>) —

    Addability statuses



53
54
55
 
# File 'lib/anki_connect/notes.rb', line 53

def note_addability_statuses(notes)
  request(:canAddNotes, notes: notes.map { |note| normalize_note(note) })
end

#note_addable?(note) ⇒ Boolean

Checks if one note can be added.

Parameters:

  • note (Hash) —

    Candidate note using snake_case keys

Returns:

  • (Boolean) —

    Whether the note can be added



37
38
39
 
# File 'lib/anki_connect/notes.rb', line 37

def note_addable?(note)
  request(:canAddNote, note: normalize_note(note))
end

#note_modification_times(note_ids) ⇒ Array<Hash>

Gets modification times for notes.

Parameters:

  • note_ids (Array<Integer>) —

    Array of note IDs

Returns:

  • (Array<Hash>) —

    Array of objects with noteId and mod



198
199
200
 
# File 'lib/anki_connect/notes.rb', line 198

def note_modification_times(note_ids)
  request(:notesModTime, notes: note_ids)
end

#note_tags(note_id) ⇒ Array<String>

Gets tags for a note.

Parameters:

  • note_id (Integer) —

    Note ID

Returns:

  • (Array<String>) —

    Array of tag strings



122
123
124
 
# File 'lib/anki_connect/notes.rb', line 122

def note_tags(note_id)
  request(:getNoteTags, note: note_id)
end

#notes(note_ids: nil, query: nil) ⇒ Array<Hash>

Gets detailed information about notes.

Parameters:

  • note_ids (Array<Integer>, nil) (defaults to: nil) —

    Array of note IDs

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

    Search query string

Returns:

  • (Array<Hash>) —

    Array of note objects



185
186
187
188
189
190
191
192
 
# File 'lib/anki_connect/notes.rb', line 185

def notes(note_ids: nil, query: nil)
  unless [note_ids, query].count { |selector| !selector.nil? } == 1
    raise ArgumentError, 'provide exactly one of note_ids or query'
  end

  params = note_ids.nil? ? { query: query } : { notes: note_ids }
  request(:notesInfo, **params)
end

#remove_tags(note_ids, tags) ⇒ nil

Removes tags from notes.

Parameters:

  • note_ids (Array<Integer>) —

    Array of note IDs

  • tags (String, Array<String>) —

    Tag(s) to remove

Returns:

  • (nil) 


140
141
142
 
# File 'lib/anki_connect/notes.rb', line 140

def remove_tags(note_ids, tags)
  request(:removeTags, notes: note_ids, tags: normalize_tag_query(tags))
end

#remove_unused_note_types ⇒ nil

Removes note types that are not used by any notes. The upstream action name is misleading; it does not remove notes with empty fields.

Returns:

  • (nil) 


214
215
216
 
# File 'lib/anki_connect/notes.rb', line 214

def remove_unused_note_types
  request(:removeEmptyNotes)
end

#replace_tag(from:, to:, note_ids: nil) ⇒ nil

Replaces a tag with another.

Parameters:

  • from (String) —

    Old tag

  • to (String) —

    New tag

  • note_ids (Array<Integer>, nil) (defaults to: nil) —

    Specific notes, or nil for all notes

Returns:

  • (nil) 


164
165
166
167
168
169
170
 
# File 'lib/anki_connect/notes.rb', line 164

def replace_tag(from:, to:, note_ids: nil)
  if note_ids
    request(:replaceTags, notes: note_ids, tag_to_replace: from, replace_with_tag: to)
  else
    request(:replaceTagsInAllNotes, tag_to_replace: from, replace_with_tag: to)
  end
end

#search_notes(query) ⇒ Array<Integer>

Searches for notes matching a query.

Parameters:

  • query (String) —

    Search query string

Returns:

  • (Array<Integer>) —

    Array of note IDs



176
177
178
 
# File 'lib/anki_connect/notes.rb', line 176

def search_notes(query)
  request(:findNotes, query: query)
end

#tags ⇒ Array<String>

Gets all tags in collection.

Returns:

  • (Array<String>) —

    Array of all tag strings



147
148
149
 
# File 'lib/anki_connect/notes.rb', line 147

def tags
  request(:getTags)
end

#update_note(id, fields: nil, tags: nil, media: nil) ⇒ nil

Updates a note's fields, tags, or media.

Parameters:

  • id (Integer) —

    Note ID

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

    Field names to new values

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

    New tags (replaces existing)

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

    Media to add (audio:, video:, picture: arrays)

Returns:

  • (nil) 


72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/anki_connect/notes.rb', line 72

def update_note(id, fields: nil, tags: nil, media: nil)
  if fields.nil? && tags.nil? && media.nil?
    raise ArgumentError, 'provide fields, tags, or media to update'
  end

  note = { id: id }
  note[:fields] = fields || {} unless fields.nil? && media.nil?
  note[:tags] = tags unless tags.nil?
  merge_media!(note, media) unless media.nil?
  request(:updateNote, note: note)
end

#update_note_fields(id, fields:, media: nil) ⇒ nil

Updates a note's fields and optional media.

Parameters:

  • id (Integer) —

    Note ID

  • fields (Hash) —

    Field names to new values

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

    Media to add (audio:, video:, picture:)

Returns:

  • (nil) 


90
91
92
93
94
 
# File 'lib/anki_connect/notes.rb', line 90

def update_note_fields(id, fields:, media: nil)
  note = { id: id, fields: fields }
  merge_media!(note, media) unless media.nil?
  request(:updateNoteFields, note: note)
end

#update_note_tags(id, tags) ⇒ nil

Replaces all tags on a note.

Parameters:

  • id (Integer) —

    Note ID

  • tags (String, Array<String>) —

    Replacement tags

Returns:

  • (nil) 


101
102
103
 
# File 'lib/anki_connect/notes.rb', line 101

def update_note_tags(id, tags)
  request(:updateNoteTags, note: id, tags: normalize_note_tags(tags))
end