typesense 0.7.0.pre0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 680a4251ea189d959a84665eb824d50efabdbe3359be1f787f23d9ea230ab16f
-  data.tar.gz: cdbb99c7ab1d32408c7100c3d1167a1ce8d1177014b80051ad4a5e2c13fbec99
+  metadata.gz: 717b58a0ddf1e2e262d8cf0e4c0a5e3e2f90a8e0cb259337a5d243a3fb0f901c
+  data.tar.gz: 89a094ce8f884ce68d068122b91a6a2df733cc7e77b128e49dd3396cb4c2f5ce
 SHA512:
-  metadata.gz: b161ddf9e1d3445934c77444d0a7d4cfb2ae6efb8879dd9f15020d286f4347bcb40933c7ad201b5d9b8cc5a3848b484586984bb07d7ac584a3e325941f08ca50
-  data.tar.gz: 04506357d9defab42a6c85d3c06b963670050944a26e6e0378cbca06b82ad2254312de2862f1fab72d8106a0dcebdc42c3c92c96bb596da9d67de4cfd1b0295c
+  metadata.gz: 69bbef4fea77ec0a97aa15d34a12168d5853c7eccb4a86866605fc536f8348fb80a31e807ff3b25ae342f95ff3569b421c54fd383164646a1585174bf66ad402
+  data.tar.gz: 8abf2ce30d9858d76150c8f81534d7f3e9bc6ad06a4fc33c2c01e0e6ffcfe49e7b0d02282e862bc95c5574a538966cc51c2f39e43e843abbb68333ef43f368da

data/README.md

@@ -25,7 +25,7 @@ Or install it yourself as:
 
 You'll find detailed documentation here: [https://typesense.org/api/](https://typesense.org/api/)
 
-Here are some examples that show you how the Ruby client works: [examples](examples)
+Here are some examples with inline comments that walk you through how to use the Ruby client: [examples](examples)
 
 Tests are also a good place to know how the the library works internally: [spec](spec)
 
@@ -33,6 +33,8 @@ Tests are also a good place to know how the the library works internally: [spec]
 
 | Typesense Server | typesense-ruby |
 |------------------|----------------|
+| \>= v0.17.0 | \>= v0.9.0 |
+| \>= v0.16.0 | \>= v0.8.0 |
 | \>= v0.15.0 | \>= v0.7.0 |
 | \>= v0.12.1 | \>= v0.5.0 |
 | \>= v0.12.0 | \>= v0.4.0 |

data/examples/client_initialization.rb

@@ -38,26 +38,26 @@ AwesomePrint.defaults = {
       host: 'localhost',
       port: 8108,
       protocol: 'http'
-    },
-    # Uncomment if starting a 3-node cluster, using Option 2 under Setup instructions above
-    {
-      host: 'localhost',
-      port: 7108,
-      protocol: 'http'
-    },
-    {
-      host: 'localhost',
-      port: 9108,
-      protocol: 'http'
     }
+    # Uncomment if starting a 3-node cluster, using Option 2 under Setup instructions above
+    # {
+    #   host: 'localhost',
+    #   port: 7108,
+    #   protocol: 'http'
+    # },
+    # {
+    #   host: 'localhost',
+    #   port: 9108,
+    #   protocol: 'http'
+    # }
   ],
   # If this optional key is specified, requests are always sent to this node first if it is healthy
   #   before falling back on the nodes mentioned in the `nodes` key. This is useful when running a distributed set of search clusters.
-  'nearest_node': {
-    'host': 'localhost',
-    'port': '8108',
-    'protocol': 'http'
-  },
+  # 'nearest_node': {
+  #   'host': 'localhost',
+  #   'port': '8108',
+  #   'protocol': 'http'
+  # },
   api_key: 'xyz',
   num_retries: 10,
   healthcheck_interval_seconds: 1,

data/examples/collections_and_documents.rb

@@ -167,6 +167,10 @@ ap document
 #   "num_employees" => 5215
 # }
 
+# You can also upsert a document, which will update the document if it already exists or create a new one if it doesn't exist
+document = @typesense.collections['companies'].documents.upsert(document)
+ap document
+
 ##
 # Retrieve a document
 sleep 0.5 # Give Typesense cluster a few hundred ms to create the document on all nodes, before reading it right after (eventually consistent)
@@ -180,6 +184,25 @@ ap document
 #   "num_employees" => 5215
 # }
 
+##
+# Update a document. Unlike upsert, update will error out if the doc doesn't already exist.
+document = @typesense.collections['companies'].documents['124'].update(
+  'id' => 1,
+  'num_employees' => 5500
+)
+ap document
+
+# {
+#   "id"            => "124",
+#   "num_employees" => 5500
+# }
+
+# This should error out, since document 145 doesn't exist
+# document = @typesense.collections['companies'].documents['145'].update(
+#   'num_employees' => 5500
+# )
+# ap document
+
 ##
 # Delete a document
 #   Deleting a document, returns the document after deletion
@@ -208,19 +231,44 @@ documents = [
     'country' => 'France'
   }
 ]
-ap @typesense.collections['companies'].documents.create_many(documents)
+ap @typesense.collections['companies'].documents.import(documents)
+
+## If you already have documents in JSONL format, you can also pass it directly to #import, to avoid the JSON parsing overhead:
+# @typesense.collections['companies'].documents.import(documents_in_jsonl_format)
+
+## You can bulk upsert documents, by adding an upsert action option to #import
+documents << {
+  'id' => '126',
+  'company_name' => 'Stark Industries 2',
+  'num_employees' => 200,
+  'country' => 'USA'
+}
+ap @typesense.collections['companies'].documents.import(documents, action: :upsert)
+
+## You can bulk update documents, by adding an update action option to #import
+# `action: update` will throw an error if the document doesn't already exist
+# This document will error out, since id: 1200 doesn't exist
+documents << {
+  'id' => '1200',
+  'country' => 'USA'
+}
+documents << {
+  'id' => '126',
+  'num_employees' => 300
+}
+ap @typesense.collections['companies'].documents.import(documents, action: :update)
+
+## You can also bulk delete documents, using filter_by fields:
+ap @typesense.collections['companies'].documents.delete(filter_by: 'num_employees:>100')
 
 ##
 # Export all documents in a collection in JSON Lines format
-#   We use JSON Lines format for performance reasons. You can choose to parse selected lines (elements in the array) as needed.
+#   We use JSON Lines format for performance reasons. You can choose to parse selected lines as needed, by splitting on \n.
 sleep 0.5 # Give Typesense cluster a few hundred ms to create the document on all nodes, before reading it right after (eventually consistent)
-array_of_json_strings = @typesense.collections['companies'].documents.export
-ap array_of_json_strings
+jsonl_data = @typesense.collections['companies'].documents.export
+ap jsonl_data
 
-# [
-# [0] "{\"company_name\":\"Stark Industries\",\"country\":\"USA\",\"id\":\"124\",\"num_employees\":5215}",
-# [1] "{\"company_name\":\"Acme Corp\",\"country\":\"France\",\"id\":\"125\",\"num_employees\":1002}"
-# ]
+# "{\"company_name\":\"Stark Industries\",\"country\":\"USA\",\"id\":\"124\",\"num_employees\":5215}\n{\"company_name\":\"Acme Corp\",\"country\":\"France\",\"id\":\"125\",\"num_employees\":1002}"
 
 ##
 # Cleanup

data/lib/typesense/api_call.rb

@@ -7,6 +7,8 @@ module Typesense
   class ApiCall
     API_KEY_HEADER_NAME = 'X-TYPESENSE-API-KEY'
 
+    attr_reader :logger
+
     def initialize(configuration)
       @configuration = configuration
 
@@ -24,43 +26,40 @@ module Typesense
       @current_node_index = -1
     end
 
-    def post(endpoint, parameters = {})
-      headers, body = extract_headers_and_body_from(parameters)
-
+    def post(endpoint, body_parameters = {}, query_parameters = {})
       perform_request :post,
                       endpoint,
-                      headers,
-                      body: body
+                      query_parameters: query_parameters,
+                      body_parameters: body_parameters
     end
 
-    def put(endpoint, parameters = {})
-      headers, body = extract_headers_and_body_from(parameters)
+    def patch(endpoint, body_parameters = {}, query_parameters = {})
+      perform_request :patch,
+                      endpoint,
+                      query_parameters: query_parameters,
+                      body_parameters: body_parameters
+    end
 
+    def put(endpoint, body_parameters = {}, query_parameters = {})
       perform_request :put,
                       endpoint,
-                      headers,
-                      body: body
+                      query_parameters: query_parameters,
+                      body_parameters: body_parameters
     end
 
-    def get(endpoint, parameters = {})
-      headers, query = extract_headers_and_query_from(parameters)
-
+    def get(endpoint, query_parameters = {})
       perform_request :get,
                       endpoint,
-                      headers,
-                      params: query
+                      query_parameters: query_parameters
     end
 
-    def delete(endpoint, parameters = {})
-      headers, query = extract_headers_and_query_from(parameters)
-
+    def delete(endpoint, query_parameters = {})
       perform_request :delete,
                       endpoint,
-                      headers,
-                      params: query
+                      query_parameters: query_parameters
     end
 
-    def perform_request(method, endpoint, headers = {}, options = {})
+    def perform_request(method, endpoint, query_parameters: nil, body_parameters: nil, additional_headers: {})
       @configuration.validate!
       last_exception = nil
       @logger.debug "Performing #{method.to_s.upcase} request: #{endpoint}"
@@ -70,15 +69,23 @@ module Typesense
         @logger.debug "Attempting #{method.to_s.upcase} request Try ##{num_tries} to Node #{node[:index]}"
 
         begin
-          response = Typhoeus::Request.new(uri_for(endpoint, node),
-                                           {
-                                             method: method,
-                                             headers: default_headers.merge(headers),
-                                             timeout: @connection_timeout_seconds
-                                           }.merge(options)).run
+          request_options = {
+            method: method,
+            timeout: @connection_timeout_seconds,
+            headers: default_headers.merge(additional_headers)
+          }
+          request_options.merge!(params: query_parameters) unless query_parameters.nil?
+
+          unless body_parameters.nil?
+            body = body_parameters
+            body = Oj.dump(body_parameters) if request_options[:headers]['Content-Type'] == 'application/json'
+            request_options.merge!(body: body)
+          end
+
+          response = Typhoeus::Request.new(uri_for(endpoint, node), request_options).run
           set_node_healthcheck(node, is_healthy: true) if response.code >= 1 && response.code <= 499
 
-          @logger.debug "Request to Node #{node[:index]} was successfully made (at the network layer). Response Code was #{response.code}."
+          @logger.debug "Request #{method}:#{uri_for(endpoint, node)} to Node #{node[:index]} was successfully made (at the network layer). Response Code was #{response.code}."
 
           parsed_response = if response.headers && (response.headers['content-type'] || '').include?('application/json')
                               Oj.load(response.body)
@@ -91,8 +98,7 @@ module Typesense
 
           exception_message = (parsed_response && parsed_response['message']) || 'Error'
           raise custom_exception_klass_for(response), exception_message
-        rescue SocketError, EOFError,
-               Errno::EINVAL, Errno::ENETDOWN, Errno::ENETUNREACH, Errno::ENETRESET, Errno::ECONNABORTED, Errno::ECONNRESET,
+        rescue Errno::EINVAL, Errno::ENETDOWN, Errno::ENETUNREACH, Errno::ENETRESET, Errno::ECONNABORTED, Errno::ECONNRESET,
                Errno::ETIMEDOUT, Errno::ECONNREFUSED, Errno::EHOSTDOWN, Errno::EHOSTUNREACH,
                Typesense::Error::TimeoutError, Typesense::Error::ServerError, Typesense::Error::HTTPStatus0Error => e
           # Rescue network layer exceptions and HTTP 5xx errors, so the loop can continue.
@@ -100,7 +106,7 @@ module Typesense
           #   other languages that might not support the same construct.
           set_node_healthcheck(node, is_healthy: false)
           last_exception = e
-          @logger.warn "Request to Node #{node[:index]} failed due to \"#{e.class}: #{e.message}\""
+          @logger.warn "Request #{method}:#{uri_for(endpoint, node)} to Node #{node[:index]} failed due to \"#{e.class}: #{e.message}\""
           @logger.warn "Sleeping for #{@retry_interval_seconds}s and then retrying request..."
           sleep @retry_interval_seconds
         end
@@ -111,41 +117,6 @@ module Typesense
 
     private
 
-    def extract_headers_and_body_from(parameters)
-      if json_request?(parameters)
-        headers = { 'Content-Type' => 'application/json' }
-        body = Oj.dump(sanitize_parameters(parameters))
-      else
-        headers = {}
-        body = parameters[:body]
-      end
-      [headers, body]
-    end
-
-    def extract_headers_and_query_from(parameters)
-      if json_request?(parameters)
-        headers = { 'Content-Type' => 'application/json' }
-        query = sanitize_parameters(parameters)
-      else
-        headers = {}
-        query = parameters[:query]
-      end
-      [headers, query]
-    end
-
-    def json_request?(parameters)
-      parameters[:as_json].nil? ? true : parameters[:as_json]
-    end
-
-    def sanitize_parameters(parameters)
-      sanitized_parameters = parameters.dup
-      sanitized_parameters.delete(:as_json)
-      sanitized_parameters.delete(:body)
-      sanitized_parameters.delete(:query)
-
-      sanitized_parameters
-    end
-
     def uri_for(endpoint, node)
       "#{node[:protocol]}://#{node[:host]}:#{node[:port]}#{endpoint}"
     end
@@ -228,6 +199,7 @@ module Typesense
 
     def default_headers
       {
+        'Content-Type' => 'application/json',
         API_KEY_HEADER_NAME.to_s => @api_key,
         'User-Agent' => 'Typesense Ruby Client'
       }

data/lib/typesense/document.rb

@@ -16,6 +16,10 @@ module Typesense
       @api_call.delete(endpoint_path)
     end
 
+    def update(partial_document)
+      @api_call.patch(endpoint_path, partial_document)
+    end
+
     private
 
     def endpoint_path

data/lib/typesense/documents.rb

@@ -16,14 +16,40 @@ module Typesense
       @api_call.post(endpoint_path, document)
     end
 
-    def create_many(documents)
-      documents_in_jsonl_format = documents.map { |document| Oj.dump(document) }.join("\n")
-      results_in_jsonl_format = import(documents_in_jsonl_format)
-      results_in_jsonl_format.split("\n").map { |r| Oj.load(r) }
+    def upsert(document)
+      @api_call.post(endpoint_path, document, action: :upsert)
     end
 
-    def import(documents_in_jsonl_format)
-      @api_call.post(endpoint_path('import'), as_json: false, body: documents_in_jsonl_format)
+    def update(document)
+      @api_call.post(endpoint_path, document, action: :update)
+    end
+
+    def create_many(documents, options = {})
+      @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')
+      import(documents, options)
+    end
+
+    # @param [Array,String] documents An array of document hashes or a JSONL string of documents.
+    def import(documents, options = {})
+      documents_in_jsonl_format = if documents.is_a?(Array)
+                                    documents.map { |document| Oj.dump(document) }.join("\n")
+                                  else
+                                    documents
+                                  end
+
+      results_in_jsonl_format = @api_call.perform_request(
+        'post',
+        endpoint_path('import'),
+        query_parameters: options,
+        body_parameters: documents_in_jsonl_format,
+        additional_headers: { 'Content-Type' => 'text/plain' }
+      )
+
+      if documents.is_a?(Array)
+        results_in_jsonl_format.split("\n").map { |r| Oj.load(r) }
+      else
+        results_in_jsonl_format
+      end
     end
 
     def export
@@ -38,6 +64,10 @@ module Typesense
       @documents[document_id] ||= Document.new(@collection_name, document_id, @api_call)
     end
 
+    def delete(query_parameters = {})
+      @api_call.delete(endpoint_path, query_parameters)
+    end
+
     private
 
     def endpoint_path(operation = nil)

data/lib/typesense/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typesense
-  VERSION = '0.7.0.pre0'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typesense
 version: !ruby/object:Gem::Version
-  version: 0.7.0.pre0
+  version: 0.9.0
 platform: ruby
 authors:
 - Typesense, Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-15 00:00:00.000000000 Z
+date: 2020-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -309,9 +309,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.0.6
 signing_key: