typesense 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01637fffe88f9d21ae627407e69a06a8beb22e0989f1638b11cc38f0bb19f449
-  data.tar.gz: 9edee26c48191b1f49befe6b2d865b20a3efbb6e70bc78a31c15da83b93f8d3b
+  metadata.gz: 5acfb1b3cbcfd880a7d8fa39a759ad2cb82396e159cdac02d64e72a4047ca264
+  data.tar.gz: 1e6d7ca55d559a86842e79e4ffb4db18327206e78c45ff039ff2a8fa59822a7b
 SHA512:
-  metadata.gz: d42ae36979f4c7fcf72c53010e46a6fab5a97ab7dab81c11bbb40289175633db821c7f552578441c265078cac72f11735ee2a61d5f7c565c6e26e8a1c1ce8cf6
-  data.tar.gz: e80e0d6e7f921650729334097e19963279146a16bb16a9365c1020c6c94560e97e7693322fc318651769e846fdbf5daf447cedbf9120a5060b79d3582cde6eaa
+  metadata.gz: 9fa4e3d1155043c18f873ee936eb5bf223d7faac05f99d311afaab9dd49faf2ba9088cf274c6c7402742422d951900f52626480f139949b6ad25e2245ba2f287
+  data.tar.gz: fe7fe260705cab7bf02dd0ebf28395860ce27a047e7ff8687c4fed5cbc4baf8aa4f79be4fb2ba08897b0f50eaa6861a9d9b9f4a7647ad959a8387c563b1c1c69

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.16.0 | \>= v0.8.0 |
+| \>= v0.15.0 | \>= v0.7.0 |
 | \>= v0.12.1 | \>= v0.5.0 |
 | \>= v0.12.0 | \>= v0.4.0 |
 | <= v0.11 | <= v0.3.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,41 @@ 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)
 
 ##
 # 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,17 +16,44 @@ 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")
-      import(documents_in_jsonl_format)
+    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
-      (@api_call.get(endpoint_path('export')) || '').split("\n")
+      @api_call.get(endpoint_path('export'))
     end
 
     def search(search_parameters)

data/lib/typesense/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typesense
-  VERSION = '0.6.0'
+  VERSION = '0.8.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typesense
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Typesense, Inc.
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-01 00:00:00.000000000 Z
+date: 2020-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -298,7 +298,7 @@ homepage: https://typesense.org
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -314,7 +314,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.0.6
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Ruby Library for Typesense
 test_files: []