typesense 5.0.0 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/tests.yml +2 -2
  3. data/.rubocop.yml +9 -1
  4. data/Gemfile +3 -7
  5. data/README.md +41 -0
  6. data/docker-compose.yml +1 -1
  7. data/flake.lock +61 -0
  8. data/flake.nix +56 -0
  9. data/lib/typesense/alias.rb +12 -0
  10. data/lib/typesense/aliases.rb +20 -0
  11. data/lib/typesense/analytics.rb +19 -0
  12. data/lib/typesense/analytics_events.rb +12 -0
  13. data/lib/typesense/analytics_events_v1.rb +6 -0
  14. data/lib/typesense/analytics_rule.rb +20 -1
  15. data/lib/typesense/analytics_rule_v1.rb +12 -0
  16. data/lib/typesense/analytics_rules.rb +34 -2
  17. data/lib/typesense/analytics_rules_v1.rb +20 -0
  18. data/lib/typesense/analytics_v1.rb +20 -0
  19. data/lib/typesense/api_call.rb +72 -5
  20. data/lib/typesense/client.rb +179 -2
  21. data/lib/typesense/collection.rb +56 -1
  22. data/lib/typesense/collections.rb +20 -0
  23. data/lib/typesense/configuration.rb +18 -4
  24. data/lib/typesense/curation_set.rb +29 -0
  25. data/lib/typesense/curation_set_item.rb +18 -0
  26. data/lib/typesense/curation_set_items.rb +14 -0
  27. data/lib/typesense/curation_sets.rb +20 -0
  28. data/lib/typesense/debug.rb +6 -0
  29. data/lib/typesense/document.rb +18 -0
  30. data/lib/typesense/documents.rb +62 -0
  31. data/lib/typesense/health.rb +6 -0
  32. data/lib/typesense/key.rb +12 -0
  33. data/lib/typesense/keys.rb +26 -0
  34. data/lib/typesense/metrics.rb +6 -0
  35. data/lib/typesense/multi_search.rb +8 -0
  36. data/lib/typesense/nl_search_model.rb +18 -0
  37. data/lib/typesense/nl_search_models.rb +20 -0
  38. data/lib/typesense/operations.rb +6 -0
  39. data/lib/typesense/override.rb +12 -0
  40. data/lib/typesense/overrides.rb +20 -0
  41. data/lib/typesense/preset.rb +12 -0
  42. data/lib/typesense/presets.rb +20 -0
  43. data/lib/typesense/stats.rb +6 -0
  44. data/lib/typesense/stemming.rb +11 -0
  45. data/lib/typesense/stemming_dictionaries.rb +20 -0
  46. data/lib/typesense/stemming_dictionary.rb +6 -0
  47. data/lib/typesense/synonym.rb +13 -0
  48. data/lib/typesense/synonym_set.rb +36 -0
  49. data/lib/typesense/synonym_set_item.rb +47 -0
  50. data/lib/typesense/synonym_set_items.rb +39 -0
  51. data/lib/typesense/synonym_sets.rb +20 -0
  52. data/lib/typesense/synonyms.rb +21 -0
  53. data/lib/typesense/version.rb +1 -1
  54. data/lib/typesense.rb +2 -0
  55. data/typesense.gemspec +5 -5
  56. metadata +46 -11
@@ -1,9 +1,186 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Typesense
4
+ # Typesense client for indexing, searching, and managing collections.
5
+ #
6
+ # @see https://typesense.org/docs/latest/api/
4
7
  class Client
5
- attr_reader :configuration, :collections, :aliases, :keys, :debug, :health, :metrics, :stats, :operations,
6
- :multi_search, :analytics, :analytics_v1, :presets, :stemming, :nl_search_models, :synonym_sets, :curation_sets
8
+ # @return [Configuration]
9
+ attr_reader :configuration
10
+
11
+ # Access the collections resource. Use it to list or create collections, or as an array to access a single collection by name.
12
+ #
13
+ # @example
14
+ # client.collections.create('name' => 'products', 'fields' => [{ 'name' => 'title', 'type' => 'string' }])
15
+ # @example
16
+ # client.collections['products'].retrieve
17
+ #
18
+ # @see https://typesense.org/docs/latest/api/collections.html
19
+ #
20
+ # @return [Collections]
21
+ attr_reader :collections
22
+
23
+ # Access the aliases resource. Use it to upsert or list aliases, or as an array to access a single alias by name.
24
+ #
25
+ # @example
26
+ # client.aliases.upsert('my-alias', 'collection_name' => 'products')
27
+ # @example
28
+ # client.aliases['my-alias'].retrieve
29
+ #
30
+ # @see https://typesense.org/docs/latest/api/collection-alias.html
31
+ #
32
+ # @return [Aliases]
33
+ attr_reader :aliases
34
+
35
+ # Access the API keys resource. Use it to create or list keys, or as an array to access a single key by ID.
36
+ #
37
+ # @example
38
+ # client.keys.create('description' => 'Search-only key', 'actions' => ['documents:search'], 'collections' => ['*'])
39
+ # @example
40
+ # client.keys[1].retrieve
41
+ #
42
+ # @see https://typesense.org/docs/latest/api/api-keys.html
43
+ #
44
+ # @return [Keys]
45
+ attr_reader :keys
46
+
47
+ # Retrieve server version and state information.
48
+ #
49
+ # @example
50
+ # client.debug.retrieve
51
+ #
52
+ # @see https://typesense.org/docs/latest/api/cluster-operations.html#debug
53
+ #
54
+ # @return [Debug]
55
+ attr_reader :debug
56
+
57
+ # Checks if Typesense server is ready to accept requests.
58
+ #
59
+ # @example
60
+ # client.health.retrieve
61
+ #
62
+ # @see https://typesense.org/docs/latest/api/cluster-operations.html#health
63
+ #
64
+ # @return [Health]
65
+ attr_reader :health
66
+
67
+ # Get current RAM, CPU, Disk & Network usage metrics.
68
+ #
69
+ # @example
70
+ # client.metrics.retrieve
71
+ #
72
+ # @see https://typesense.org/docs/latest/api/cluster-operations.html
73
+ #
74
+ # @return [Metrics]
75
+ attr_reader :metrics
76
+
77
+ # Get stats about API endpoints.
78
+ #
79
+ # @example
80
+ # client.stats.retrieve
81
+ #
82
+ # @see https://typesense.org/docs/latest/api/cluster-operations.html
83
+ #
84
+ # @return [Stats]
85
+ attr_reader :stats
86
+
87
+ # Cluster operations: snapshots, voting, cache, on-disk compaction, slow request log.
88
+ #
89
+ # @example
90
+ # client.operations.perform('snapshot', 'snapshot_path' => '/tmp/snap')
91
+ #
92
+ # @see https://typesense.org/docs/latest/api/cluster-operations.html
93
+ #
94
+ # @return [Operations]
95
+ attr_reader :operations
96
+
97
+ # Send multiple search requests in a single HTTP request.
98
+ #
99
+ # @example
100
+ # client.multi_search.perform('searches' => [{ 'collection' => 'products', 'q' => '*' }])
101
+ #
102
+ # @see https://typesense.org/docs/latest/api/documents.html#federated-multi-search
103
+ #
104
+ # @return [MultiSearch]
105
+ attr_reader :multi_search
106
+
107
+ # Manage analytics rules and events.
108
+ #
109
+ # @example
110
+ # client.analytics.rules.retrieve
111
+ #
112
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
113
+ #
114
+ # @return [Analytics]
115
+ attr_reader :analytics
116
+
117
+ # Legacy v1 analytics API for rules and events.
118
+ #
119
+ # @example
120
+ # client.analytics_v1.rules.retrieve
121
+ #
122
+ # @see https://typesense.org/docs/latest/api/analytics-query-suggestions.html
123
+ #
124
+ # @return [AnalyticsV1]
125
+ attr_reader :analytics_v1
126
+
127
+ # Access the presets resource. Use it to upsert or list presets, or as an array to access a single preset by name.
128
+ #
129
+ # @example
130
+ # client.presets.upsert('listing_view', 'value' => { 'q' => '*' })
131
+ # @example
132
+ # client.presets['listing_view'].retrieve
133
+ #
134
+ # @see https://typesense.org/docs/latest/api/search.html#presets
135
+ #
136
+ # @return [Presets]
137
+ attr_reader :presets
138
+
139
+ # Manage stemming dictionaries.
140
+ #
141
+ # @example
142
+ # client.stemming.dictionaries.retrieve
143
+ #
144
+ # @see https://typesense.org/docs/latest/api/stemming.html
145
+ #
146
+ # @return [Stemming]
147
+ attr_reader :stemming
148
+
149
+ # Access the NL search models resource. Use it to create or list models, or as an array to access a single model by ID.
150
+ #
151
+ # @example
152
+ # client.nl_search_models.create('model_name' => 'openai/gpt-4')
153
+ # @example
154
+ # client.nl_search_models['model-1'].retrieve
155
+ #
156
+ # @see https://typesense.org/docs/latest/api/natural-language-search.html
157
+ #
158
+ # @return [NlSearchModels]
159
+ attr_reader :nl_search_models
160
+
161
+ # Access the synonym sets resource. Use it to upsert or list sets, or as an array to access a single set by name.
162
+ #
163
+ # @example
164
+ # client.synonym_sets.retrieve
165
+ # @example
166
+ # client.synonym_sets['my-set'].retrieve
167
+ #
168
+ # @see https://typesense.org/docs/latest/api/synonyms.html
169
+ #
170
+ # @return [SynonymSets]
171
+ attr_reader :synonym_sets
172
+
173
+ # Access the curation sets resource. Use it to upsert or list sets, or as an array to access a single set by name.
174
+ #
175
+ # @example
176
+ # client.curation_sets.retrieve
177
+ # @example
178
+ # client.curation_sets['my-set'].retrieve
179
+ #
180
+ # @see https://typesense.org/docs/latest/api/curation.html
181
+ #
182
+ # @return [CurationSets]
183
+ attr_reader :curation_sets
7
184
 
8
185
  def initialize(options = {})
9
186
  @configuration = Configuration.new(options)
@@ -2,7 +2,44 @@
2
2
 
3
3
  module Typesense
4
4
  class Collection
5
- attr_reader :documents, :overrides, :synonyms
5
+ # Access the documents resource for this collection. Use it to list, index, search, import, or export documents,
6
+ # or as an array to access a single document by ID.
7
+ #
8
+ # @example
9
+ # client.collections['products'].documents.create('id' => '1', 'title' => 'Hat')
10
+ # @example
11
+ # client.collections['products'].documents['1'].retrieve
12
+ #
13
+ # @see https://typesense.org/docs/latest/api/documents.html
14
+ #
15
+ # @return [Documents]
16
+ attr_reader :documents
17
+
18
+ # Access the legacy overrides (curation) resource for this collection. Use it to list or upsert overrides,
19
+ # or as an array to access a single override by ID.
20
+ #
21
+ # @example
22
+ # client.collections['products'].overrides.upsert('promote-hat', 'rule' => { 'query' => 'hat', 'match' => 'exact' }, 'includes' => [])
23
+ # @example
24
+ # client.collections['products'].overrides['promote-hat'].retrieve
25
+ #
26
+ # @see https://typesense.org/docs/latest/api/curation.html
27
+ #
28
+ # @return [Overrides]
29
+ attr_reader :overrides
30
+
31
+ # Access the legacy synonyms resource for this collection. Use it to list or upsert synonyms,
32
+ # or as an array to access a single synonym by ID.
33
+ #
34
+ # @example
35
+ # client.collections['products'].synonyms.upsert('syn-1', 'synonyms' => ['nyc', 'new york'])
36
+ # @example
37
+ # client.collections['products'].synonyms['syn-1'].retrieve
38
+ #
39
+ # @see https://typesense.org/docs/latest/api/synonyms.html
40
+ #
41
+ # @return [Synonyms]
42
+ attr_reader :synonyms
6
43
 
7
44
  def initialize(name, api_call)
8
45
  @name = name
@@ -12,14 +49,32 @@ module Typesense
12
49
  @synonyms = Synonyms.new(@name, @api_call)
13
50
  end
14
51
 
52
+ # Retrieve the details of a collection, given its name.
53
+ #
54
+ # @example
55
+ # client.collections['products'].retrieve
56
+ #
57
+ # @see https://typesense.org/docs/latest/api/collections.html#retrieve-a-collection
15
58
  def retrieve
16
59
  @api_call.get(endpoint_path)
17
60
  end
18
61
 
62
+ # Update a collection's schema to modify the fields and their types.
63
+ #
64
+ # @example
65
+ # client.collections['products'].update('fields' => [{ 'name' => 'tags', 'type' => 'string[]' }])
66
+ #
67
+ # @see https://typesense.org/docs/latest/api/collections.html#update-or-alter-a-collection
19
68
  def update(update_schema)
20
69
  @api_call.patch(endpoint_path, update_schema)
21
70
  end
22
71
 
72
+ # Permanently drops a collection. This action cannot be undone. For large collections, this might have an impact on read latencies.
73
+ #
74
+ # @example
75
+ # client.collections['products'].delete
76
+ #
77
+ # @see https://typesense.org/docs/latest/api/collections.html#drop-a-collection
23
78
  def delete
24
79
  @api_call.delete(endpoint_path)
25
80
  end
@@ -9,14 +9,34 @@ module Typesense
9
9
  @collections = {}
10
10
  end
11
11
 
12
+ # When a collection is created, we give it a name and describe the fields that will be indexed from the documents added to the collection.
13
+ #
14
+ # @example
15
+ # client.collections.create('name' => 'products', 'fields' => [{ 'name' => 'title', 'type' => 'string' }])
16
+ #
17
+ # @see https://typesense.org/docs/latest/api/collections.html#create-a-collection
12
18
  def create(schema)
13
19
  @api_call.post(RESOURCE_PATH, schema)
14
20
  end
15
21
 
22
+ # Returns a summary of all your collections. The collections are returned sorted by creation date, with the most recent collections appearing first.
23
+ #
24
+ # @example
25
+ # client.collections.retrieve
26
+ #
27
+ # @see https://typesense.org/docs/latest/api/collections.html#list-all-collections
16
28
  def retrieve(options = {})
17
29
  @api_call.get(RESOURCE_PATH, options)
18
30
  end
19
31
 
32
+ # Access an individual collection by name.
33
+ #
34
+ # @example
35
+ # client.collections['products'].retrieve
36
+ #
37
+ # @see https://typesense.org/docs/latest/api/collections.html
38
+ #
39
+ # @return [Collection]
20
40
  def [](collection_name)
21
41
  @collections[collection_name] ||= Collection.new(collection_name, @api_call)
22
42
  end
@@ -4,7 +4,7 @@ require 'logger'
4
4
 
5
5
  module Typesense
6
6
  class Configuration
7
- attr_accessor :nodes, :nearest_node, :connection_timeout_seconds, :healthcheck_interval_seconds, :num_retries, :retry_interval_seconds, :api_key, :logger, :log_level
7
+ attr_accessor :nodes, :nearest_node, :connection_timeout_seconds, :healthcheck_interval_seconds, :num_retries, :retry_interval_seconds, :api_key, :logger, :log_level, :keep_alive_connections, :keep_alive_idle_timeout_seconds, :keep_alive_pool_size
8
8
 
9
9
  def initialize(options = {})
10
10
  @nodes = options[:nodes] || []
@@ -14,16 +14,19 @@ module Typesense
14
14
  @num_retries = options[:num_retries] || (@nodes.length + (@nearest_node.nil? ? 0 : 1)) || 3
15
15
  @retry_interval_seconds = options[:retry_interval_seconds] || 0.1
16
16
  @api_key = options[:api_key]
17
+ @keep_alive_connections = options.fetch(:keep_alive_connections, false)
18
+ @keep_alive_idle_timeout_seconds = options[:keep_alive_idle_timeout_seconds] || 30
19
+ @keep_alive_pool_size = options[:keep_alive_pool_size] || 1
17
20
 
18
21
  @logger = options[:logger] || Logger.new($stdout)
19
22
  @log_level = options[:log_level] || Logger::WARN
20
23
  @logger.level = @log_level
21
24
 
22
25
  show_deprecation_warnings(options)
23
- validate!
26
+ validate!(options)
24
27
  end
25
28
 
26
- def validate!
29
+ def validate!(options = {})
27
30
  if @nodes.nil? ||
28
31
  @nodes.empty? ||
29
32
  @nodes.any? { |node| node_missing_parameters?(node) }
@@ -31,12 +34,23 @@ module Typesense
31
34
  end
32
35
 
33
36
  raise Error::MissingConfiguration, 'Missing required configuration. Ensure that api_key is set.' if @api_key.nil?
37
+
38
+ validate_keep_alive_options!(options)
34
39
  end
35
40
 
36
41
  private
37
42
 
38
43
  def node_missing_parameters?(node)
39
- %i[protocol host port].any? { |attr| node.send(:[], attr).nil? }
44
+ %i[protocol host port].any? { |attr| node[attr].nil? }
45
+ end
46
+
47
+ def validate_keep_alive_options!(options)
48
+ return if @keep_alive_connections
49
+
50
+ dependent_keys = %i[keep_alive_idle_timeout_seconds keep_alive_pool_size].select { |k| options.key?(k) }
51
+ return if dependent_keys.empty?
52
+
53
+ raise Error::MissingConfiguration, "#{dependent_keys.join(' and ')} require keep_alive_connections: true."
40
54
  end
41
55
 
42
56
  def show_deprecation_warnings(options)
@@ -2,6 +2,17 @@
2
2
 
3
3
  module Typesense
4
4
  class CurationSet
5
+ # Access the items in this curation set. Use it to list items, or as an array
6
+ # to access a single item by ID.
7
+ #
8
+ # @example
9
+ # client.curation_sets['my-set'].items.retrieve
10
+ # @example
11
+ # client.curation_sets['my-set'].items['promote-hat'].retrieve
12
+ #
13
+ # @see https://typesense.org/docs/latest/api/curation.html
14
+ #
15
+ # @return [CurationSetItems]
5
16
  attr_reader :items
6
17
 
7
18
  def initialize(curation_set_name, api_call)
@@ -10,14 +21,32 @@ module Typesense
10
21
  @items = CurationSetItems.new(@curation_set_name, @api_call)
11
22
  end
12
23
 
24
+ # Create or update a curation set with the given name
25
+ #
26
+ # @example
27
+ # client.curation_sets['my-set'].upsert('items' => [{ 'id' => 'promote-hat', 'rule' => { 'query' => 'hat', 'match' => 'exact' } }])
28
+ #
29
+ # @see https://typesense.org/docs/latest/api/curation.html
13
30
  def upsert(curation_set_data)
14
31
  @api_call.put(endpoint_path, curation_set_data)
15
32
  end
16
33
 
34
+ # Retrieve a specific curation set by its name
35
+ #
36
+ # @example
37
+ # client.curation_sets['my-set'].retrieve
38
+ #
39
+ # @see https://typesense.org/docs/latest/api/curation.html
17
40
  def retrieve
18
41
  @api_call.get(endpoint_path)
19
42
  end
20
43
 
44
+ # Delete a specific curation set by its name
45
+ #
46
+ # @example
47
+ # client.curation_sets['my-set'].delete
48
+ #
49
+ # @see https://typesense.org/docs/latest/api/curation.html
21
50
  def delete
22
51
  @api_call.delete(endpoint_path)
23
52
  end
@@ -8,14 +8,32 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Retrieve a specific curation item by its id
12
+ #
13
+ # @example
14
+ # client.curation_sets['my-set'].items['promote-hat'].retrieve
15
+ #
16
+ # @see https://typesense.org/docs/latest/api/curation.html
11
17
  def retrieve
12
18
  @api_call.get(endpoint_path)
13
19
  end
14
20
 
21
+ # Create or update a curation set item with the given id
22
+ #
23
+ # @example
24
+ # client.curation_sets['my-set'].items['promote-hat'].upsert('rule' => { 'query' => 'hat', 'match' => 'exact' }, 'includes' => [])
25
+ #
26
+ # @see https://typesense.org/docs/latest/api/curation.html
15
27
  def upsert(params)
16
28
  @api_call.put(endpoint_path, params)
17
29
  end
18
30
 
31
+ # Delete a specific curation item by its id
32
+ #
33
+ # @example
34
+ # client.curation_sets['my-set'].items['promote-hat'].delete
35
+ #
36
+ # @see https://typesense.org/docs/latest/api/curation.html
19
37
  def delete
20
38
  @api_call.delete(endpoint_path)
21
39
  end
@@ -8,10 +8,24 @@ module Typesense
8
8
  @items = {}
9
9
  end
10
10
 
11
+ # Retrieve all curation items in a set
12
+ #
13
+ # @example
14
+ # client.curation_sets['my-set'].items.retrieve
15
+ #
16
+ # @see https://typesense.org/docs/latest/api/curation.html
11
17
  def retrieve
12
18
  @api_call.get(endpoint_path)
13
19
  end
14
20
 
21
+ # Access an individual curation item by ID within this curation set.
22
+ #
23
+ # @example
24
+ # client.curation_sets['my-set'].items['promote-hat'].retrieve
25
+ #
26
+ # @see https://typesense.org/docs/latest/api/curation.html
27
+ #
28
+ # @return [CurationSetItem]
15
29
  def [](item_id)
16
30
  @items[item_id] ||= CurationSetItem.new(@curation_set_name, item_id, @api_call)
17
31
  end
@@ -8,14 +8,34 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Create or update a curation set with the given name
12
+ #
13
+ # @example
14
+ # client.curation_sets.upsert('my-set', 'items' => [{ 'id' => 'promote-hat', 'rule' => { 'query' => 'hat', 'match' => 'exact' } }])
15
+ #
16
+ # @see https://typesense.org/docs/latest/api/curation.html
11
17
  def upsert(curation_set_name, curation_set_data)
12
18
  @api_call.put("#{self.class::RESOURCE_PATH}/#{URI.encode_www_form_component(curation_set_name)}", curation_set_data)
13
19
  end
14
20
 
21
+ # Retrieve all curation sets
22
+ #
23
+ # @example
24
+ # client.curation_sets.retrieve
25
+ #
26
+ # @see https://typesense.org/docs/latest/api/curation.html
15
27
  def retrieve
16
28
  @api_call.get(self.class::RESOURCE_PATH)
17
29
  end
18
30
 
31
+ # Access an individual curation set by name.
32
+ #
33
+ # @example
34
+ # client.curation_sets['my-set'].retrieve
35
+ #
36
+ # @see https://typesense.org/docs/latest/api/curation.html
37
+ #
38
+ # @return [CurationSet]
19
39
  def [](curation_set_name)
20
40
  CurationSet.new(curation_set_name, @api_call)
21
41
  end
@@ -8,6 +8,12 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Retrieve server version and state information.
12
+ #
13
+ # @example
14
+ # client.debug.retrieve
15
+ #
16
+ # @see https://typesense.org/docs/latest/api/cluster-operations.html#debug
11
17
  def retrieve
12
18
  @api_call.get(RESOURCE_PATH)
13
19
  end
@@ -8,14 +8,32 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Fetch an individual document from a collection by using its ID.
12
+ #
13
+ # @example
14
+ # client.collections['products'].documents['1'].retrieve
15
+ #
16
+ # @see https://typesense.org/docs/latest/api/documents.html#retrieve-a-document
11
17
  def retrieve
12
18
  @api_call.get(endpoint_path)
13
19
  end
14
20
 
21
+ # Delete an individual document from a collection by using its ID.
22
+ #
23
+ # @example
24
+ # client.collections['products'].documents['1'].delete
25
+ #
26
+ # @see https://typesense.org/docs/latest/api/documents.html#delete-a-document
15
27
  def delete
16
28
  @api_call.delete(endpoint_path)
17
29
  end
18
30
 
31
+ # Update an individual document by ID by merging the provided fields.
32
+ #
33
+ # @example
34
+ # client.collections['products'].documents['1'].update('in_stock' => true)
35
+ #
36
+ # @see https://typesense.org/docs/latest/api/documents.html#update-a-document
19
37
  def update(partial_document, options = {})
20
38
  @api_call.patch(endpoint_path, partial_document, options)
21
39
  end
@@ -12,14 +12,34 @@ module Typesense
12
12
  @documents = {}
13
13
  end
14
14
 
15
+ # Index a single document. The document must conform to the schema of the collection.
16
+ #
17
+ # @example
18
+ # client.collections['products'].documents.create('id' => '1', 'title' => 'Hat')
19
+ #
20
+ # @see https://typesense.org/docs/latest/api/documents.html#index-a-single-document
15
21
  def create(document, options = {})
16
22
  @api_call.post(endpoint_path, document, options)
17
23
  end
18
24
 
25
+ # Upsert a single document. Creates the document if it does not exist, otherwise updates it.
26
+ #
27
+ # @example
28
+ # client.collections['products'].documents.upsert('id' => '1', 'title' => 'Hat')
29
+ #
30
+ # @see https://typesense.org/docs/latest/api/documents.html#upsert
19
31
  def upsert(document, options = {})
20
32
  @api_call.post(endpoint_path, document, options.merge(action: :upsert))
21
33
  end
22
34
 
35
+ # Update documents matching a `filter_by` condition, or update a single document with `action: "update"` semantics.
36
+ #
37
+ # @example
38
+ # client.collections['products'].documents.update({ 'in_stock' => true }, filter_by: 'category:=hats')
39
+ # @example
40
+ # client.collections['products'].documents.update('id' => '1', 'title' => 'Hat')
41
+ #
42
+ # @see https://typesense.org/docs/latest/api/documents.html#update-documents-with-conditional-query
23
43
  def update(document, options = {})
24
44
  if options['filter_by'] || options[:filter_by]
25
45
  @api_call.patch(endpoint_path, document, options)
@@ -28,11 +48,21 @@ module Typesense
28
48
  end
29
49
  end
30
50
 
51
+ # @deprecated Use {#import} instead, which accepts both an array of documents or a JSONL string.
31
52
  def create_many(documents, options = {})
32
53
  @api_call.logger.warn('#create_many is deprecated and will be removed in a future version. Use #import instead, which now takes both an array of documents or a JSONL string of documents')
33
54
  import(documents, options)
34
55
  end
35
56
 
57
+ # Import documents into a collection. Accepts a JSONL string or an array of document hashes.
58
+ #
59
+ # @example
60
+ # client.collections['products'].documents.import([{ 'id' => '1', 'title' => 'Hat' }, { 'id' => '2', 'title' => 'Shirt' }])
61
+ # @example
62
+ # client.collections['products'].documents.import(jsonl_string)
63
+ #
64
+ # @see https://typesense.org/docs/latest/api/documents.html#index-multiple-documents
65
+ #
36
66
  # @param [Array,String] documents An array of document hashes or a JSONL string of documents.
37
67
  def import(documents, options = {})
38
68
  documents_in_jsonl_format = if documents.is_a?(Array)
@@ -65,22 +95,54 @@ module Typesense
65
95
  end
66
96
  end
67
97
 
98
+ # Export all documents in a collection as a JSONL string.
99
+ #
100
+ # @example
101
+ # client.collections['products'].documents.export
102
+ #
103
+ # @see https://typesense.org/docs/latest/api/documents.html#export-documents
68
104
  def export(options = {})
69
105
  @api_call.get(endpoint_path('export'), options)
70
106
  end
71
107
 
108
+ # Search for documents in a collection that match the search criteria.
109
+ #
110
+ # @example
111
+ # client.collections['products'].documents.search('q' => '*', 'query_by' => 'title')
112
+ #
113
+ # @see https://typesense.org/docs/latest/api/search.html
72
114
  def search(search_parameters)
73
115
  @api_call.get(endpoint_path('search'), search_parameters)
74
116
  end
75
117
 
118
+ # Access an individual document by ID within this collection.
119
+ #
120
+ # @example
121
+ # client.collections['products'].documents['1'].retrieve
122
+ #
123
+ # @see https://typesense.org/docs/latest/api/documents.html
124
+ #
125
+ # @return [Document]
76
126
  def [](document_id)
77
127
  @documents[document_id] ||= Document.new(@collection_name, document_id, @api_call)
78
128
  end
79
129
 
130
+ # Delete a bunch of documents that match a specific filter condition.
131
+ #
132
+ # @example
133
+ # client.collections['products'].documents.delete(filter_by: 'in_stock:=false')
134
+ #
135
+ # @see https://typesense.org/docs/latest/api/documents.html#delete-by-query
80
136
  def delete(query_parameters = {})
81
137
  @api_call.delete(endpoint_path, query_parameters)
82
138
  end
83
139
 
140
+ # Truncate all documents in the collection.
141
+ #
142
+ # @example
143
+ # client.collections['products'].documents.truncate
144
+ #
145
+ # @see https://typesense.org/docs/latest/api/documents.html#delete-by-query
84
146
  def truncate
85
147
  @api_call.delete(endpoint_path, { truncate: true })
86
148
  end
@@ -8,6 +8,12 @@ module Typesense
8
8
  @api_call = api_call
9
9
  end
10
10
 
11
+ # Checks if Typesense server is ready to accept requests.
12
+ #
13
+ # @example
14
+ # client.health.retrieve
15
+ #
16
+ # @see https://typesense.org/docs/latest/api/cluster-operations.html#health
11
17
  def retrieve
12
18
  @api_call.get(RESOURCE_PATH)
13
19
  end