typesense 0.1.0 → 0.5.1

data/examples/client_initialization.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../lib/typesense'
+require 'awesome_print'
+
+AwesomePrint.defaults = {
+  indent: -2
+}
+
+##
+## Setup
+#
+### Option 1: Start a single-node cluster
+#     $ docker run -i -p 8108:8108 -v/tmp/typesense-server-data-1b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.1.rc1 --data-dir /data --api-key=xyz --listen-port 8108 --enable-cors
+#
+### Option 2: Start a 3-node cluster
+#
+# Create file in present working directory called typesense-server-peers (update IP Addresses appropriately to your local network):
+#   $ echo '172.17.0.2:8107:8108,172.17.0.3:7107:7108,172.17.0.4:9107:9108' > `pwd`/typesense-server-peers
+#
+# Start node 1:
+#   $ docker run -i -p 8108:8108 -p 8107:8107 -v/tmp/typesense-server-data-1b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.1.rc1 --data-dir /data --api-key=xyz --listen-port 8108 --peering-port 8107 --enable-cors --nodes=/typesense-server-peers
+#
+# Start node 2:
+#   $ docker run -i -p 7108:7108 -p 7107:7107 -v/tmp/.typesense-server-data-2b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.1.rc1 --data-dir /data --api-key=xyz --listen-port 7108 --peering-port 7107 --enable-cors --nodes=/typesense-server-peers
+#
+# Start node 3:
+#   $ docker run -i -p 9108:9108 -p 9107:9107 -v/tmp/.typesense-server-data-3b/:/data -v`pwd`/typesense-server-peers:/typesense-server-peers typesense/typesense:0.12.1.rc1 --data-dir /data --api-key=xyz --listen-port 9108 --peering-port 9107 --enable-cors --nodes=/typesense-server-peers
+#
+# Note: Be sure to add `--license-key=<>` at the end when starting a Typesense Premium server
+
+##
+# Create a client
+@typesense = Typesense::Client.new(
+  nodes: [
+    {
+      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'
+    }
+  ],
+  # 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'
+  },
+  api_key: 'xyz',
+  num_retries: 10,
+  healthcheck_interval_seconds: 1,
+  retry_interval_seconds: 0.01,
+  connection_timeout_seconds: 10,
+  logger: Logger.new(STDOUT),
+  log_level: Logger::DEBUG
+)

data/examples/collections_and_documents.rb

@@ -4,65 +4,37 @@
 # These examples walk you through all the operations you can do on a collection and a document
 # Search is specifically covered in another file in the examples folder
 
-require_relative '../lib/typesense'
-require 'awesome_print'
-
-AwesomePrint.defaults = {
-  indent: -2
-}
-
-##
-# Setup
-#
-# Start the master
-#   $ docker run -p 8108:8108  -it -v/tmp/typesense-data-master/:/data -it typesense/typesense:0.8.0-rc1 --data-dir /data --api-key=abcd --listen-port 8108
-#
-# Start the read replica
-#   $ docker run -p 8109:8109  -it -v/tmp/typesense-data-read-replica-1/:/data -it typesense/typesense:0.8.0-rc1 --data-dir /data --api-key=wxyz --listen-port 8109 --master http://localhost:8108
-
-##
-# Create a client
-typesense = Typesense::Client.new(
-  master_node:        {
-    host:     'localhost',
-    port:     8108,
-    protocol: 'http',
-    api_key:  'abcd'
-  },
-  read_replica_nodes: [
-    {
-      host:     'localhost',
-      port:     8109,
-      protocol: 'http',
-      api_key:  'wxyz'
-    }
-  ],
-  timeout_seconds:    10
-)
+require_relative './client_initialization'
 
 ##
 # Create a collection
 schema = {
-  'name'      => 'companies',
-  'fields'    => [
+  'name' => 'companies',
+  'fields' => [
     {
       'name' => 'company_name',
       'type' => 'string'
     },
     {
-      'name'  => 'num_employees',
-      'type'  => 'int32'
+      'name' => 'num_employees',
+      'type' => 'int32'
     },
     {
-      'name'  => 'country',
-      'type'  => 'string',
+      'name' => 'country',
+      'type' => 'string',
       'facet' => true
     }
   ],
   'default_sorting_field' => 'num_employees'
 }
 
-collection = typesense.collections.create(schema)
+# Delete the collection if it already exists
+begin
+  @typesense.collections['companies'].delete
+rescue Typesense::Error::ObjectNotFound
+end
+
+collection = @typesense.collections.create(schema)
 ap collection
 
 # {
@@ -87,7 +59,8 @@ ap collection
 
 ##
 # Retrieve a collection
-collection = typesense.collections['companies'].retrieve
+sleep 0.5 # Give Typesense cluster a few hundred ms to create the collection on all nodes, before reading it right after (eventually consistent)
+collection = @typesense.collections['companies'].retrieve
 ap collection
 
 # {
@@ -115,7 +88,7 @@ ap collection
 
 ##
 # Retrieve all collections
-collections = typesense.collections.retrieve
+collections = @typesense.collections.retrieve
 ap collections
 
 # [
@@ -146,7 +119,7 @@ ap collections
 ##
 # Delete a collection
 #   Deletion returns the schema of the collection after deletion
-collection = typesense.collections['companies'].delete
+collection = @typesense.collections['companies'].delete
 ap collection
 
 # {
@@ -173,18 +146,18 @@ ap collection
 # }
 
 # Let's create the collection again for use in our remaining examples
-typesense.collections.create(schema)
+@typesense.collections.create(schema)
 
 ##
 # Create (index) a document
 document = {
-  'id'            => '124',
-  'company_name'  => 'Stark Industries',
+  'id' => '124',
+  'company_name' => 'Stark Industries',
   'num_employees' => 5215,
-  'country'       => 'USA'
+  'country' => 'USA'
 }
 
-document = typesense.collections['companies'].documents.create(document)
+document = @typesense.collections['companies'].documents.create(document)
 ap document
 
 # {
@@ -196,7 +169,8 @@ ap document
 
 ##
 # Retrieve a document
-document = typesense.collections['companies'].documents['124'].retrieve
+sleep 0.5 # Give Typesense cluster a few hundred ms to create the document on all nodes, before reading it right after (eventually consistent)
+document = @typesense.collections['companies'].documents['124'].retrieve
 ap document
 
 # {
@@ -209,7 +183,7 @@ ap document
 ##
 # Delete a document
 #   Deleting a document, returns the document after deletion
-document = typesense.collections['companies'].documents['124'].delete
+document = @typesense.collections['companies'].documents['124'].delete
 ap document
 
 # {
@@ -219,25 +193,28 @@ ap document
 #   "num_employees" => 5215
 # }
 
-# Let's create two documents again for use in our remaining examples
-typesense.collections['companies'].documents.create(
-  'id' => '124',
-  'company_name' => 'Stark Industries',
-  'num_employees' => 5215,
-  'country' => 'USA'
-)
-
-typesense.collections['companies'].documents.create(
-  'id' => '125',
-  'company_name' => 'Acme Corp',
-  'num_employees' => 1002,
-  'country' => 'France'
-)
+# Let's bulk create two documents again for use in our remaining examples
+documents = [
+  {
+    'id' => '124',
+    'company_name' => 'Stark Industries',
+    'num_employees' => 5215,
+    'country' => 'USA'
+  },
+  {
+    'id' => '125',
+    'company_name' => 'Acme Corp',
+    'num_employees' => 1002,
+    'country' => 'France'
+  }
+]
+ap @typesense.collections['companies'].documents.create_many(documents)
 
 ##
 # 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.
-array_of_json_strings = typesense.collections['companies'].documents.export
+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
 
 # [
@@ -248,4 +225,4 @@ ap array_of_json_strings
 ##
 # Cleanup
 # Drop the collection
-typesense.collections['companies'].delete
+@typesense.collections['companies'].delete

data/examples/keys.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+##
+# These examples walk you through operations to manage API Keys
+
+require_relative './client_initialization'
+
+# Let's setup some test data for this example
+schema = {
+  'name' => 'users',
+  'fields' => [
+    {
+      'name' => 'company_id',
+      'type' => 'int32',
+      'facet' => false
+    },
+    {
+      'name' => 'user_name',
+      'type' => 'string',
+      'facet' => false
+    },
+    {
+      'name' => 'login_count',
+      'type' => 'int32',
+      'facet' => false
+    },
+    {
+      'name' => 'country',
+      'type' => 'string',
+      'facet' => true
+    }
+  ],
+  'default_sorting_field' => 'company_id'
+}
+
+# We have four users, belonging to two companies: 124 and 126
+documents = [
+  {
+    'company_id' => 124,
+    'user_name' => 'Hilary Bradford',
+    'login_count' => 10,
+    'country' => 'USA'
+  },
+  {
+    'company_id' => 124,
+    'user_name' => 'Nile Carty',
+    'login_count' => 100,
+    'country' => 'USA'
+  },
+  {
+    'company_id' => 126,
+    'user_name' => 'Tahlia Maxwell',
+    'login_count' => 1,
+    'country' => 'France'
+  },
+  {
+    'company_id' => 126,
+    'user_name' => 'Karl Roy',
+    'login_count' => 2,
+    'country' => 'Germany'
+  }
+]
+
+# Delete if the collection already exists from a previous example run
+begin
+  @typesense.collections['users'].delete
+rescue Typesense::Error::ObjectNotFound
+end
+
+# create a collection
+@typesense.collections.create(schema)
+
+# Index documents
+documents.each do |document|
+  @typesense.collections['users'].documents.create(document)
+end
+
+# Generate an API key and restrict it to only allow searches
+# You want to use this API Key in the browser instead of the master API Key
+unscoped_search_only_api_key_response = @typesense.keys.create({
+                                                                 'description' => 'Search-only key.',
+                                                                 'actions' => ['documents:search'],
+                                                                 'collections' => ['*']
+                                                               })
+ap unscoped_search_only_api_key_response
+
+# Save the key returned, since this will be the only time the full API Key is returned, for security purposes
+unscoped_search_only_api_key = unscoped_search_only_api_key_response['value']
+
+# Side note: you can also retrieve metadata of API keys using the ID returned in the above response
+unscoped_search_only_api_key_response = @typesense.keys[unscoped_search_only_api_key_response['id']].retrieve
+ap unscoped_search_only_api_key_response
+
+# We'll now use this search-only API key to generate a scoped search API key that can only access documents that have company_id:124
+#  This is useful when you store multi-tenant data in a single Typesense server, but you only want
+#  a particular tenant to access their own data. You'd generate one scoped search key per tenant.
+#  IMPORTANT: scoped search keys should only be generated *server-side*, so as to not leak the unscoped main search key to clients
+scoped_search_only_api_key = @typesense.keys.generate_scoped_search_key(unscoped_search_only_api_key, { 'filter_by': 'company_id:124' })
+ap "scoped_search_only_api_key: #{scoped_search_only_api_key}"
+
+# Now let's search the data using the scoped API Key for company_id:124
+# You can do searches with this scoped_search_only_api_key from the server-side or client-side
+scoped_typesense_client = Typesense::Client.new({
+                                                  'nodes': [{
+                                                    'host': 'localhost',
+                                                    'port': '8108',
+                                                    'protocol': 'http'
+                                                  }],
+                                                  'api_key': scoped_search_only_api_key
+                                                })
+
+search_results = scoped_typesense_client.collections['users'].documents.search({
+                                                                                 'q' => 'Hilary',
+                                                                                 'query_by' => 'user_name'
+                                                                               })
+ap search_results
+
+# Search for a user that exists, but is outside the current key's scope
+search_results = scoped_typesense_client.collections['users'].documents.search({
+                                                                                 'q': 'Maxwell',
+                                                                                 'query_by': 'user_name'
+                                                                               })
+ap search_results # Will return empty result set
+
+# Now let's delete the unscoped_search_only_api_key. You'd want to do this when you need to rotate keys for example.
+results = @typesense.keys[unscoped_search_only_api_key_response['id']].delete
+ap results

data/examples/overrides.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+##
+# These examples walk you through operations specifically related to overrides
+# This is a Typesense Premium feature (see: https://typesense.org/premium)
+# Be sure to add `--license-key=<>` as a parameter, when starting a Typesense Premium server
+
+require_relative './client_initialization'
+
+##
+# Create a collection
+schema = {
+  'name' => 'companies',
+  'fields' => [
+    {
+      'name' => 'company_name',
+      'type' => 'string'
+    },
+    {
+      'name' => 'num_employees',
+      'type' => 'int32'
+    },
+    {
+      'name' => 'country',
+      'type' => 'string',
+      'facet' => true
+    }
+  ],
+  'default_sorting_field' => 'num_employees'
+}
+
+@typesense.collections.create(schema)
+
+# Let's create a couple documents for us to use in our search examples
+@typesense.collections['companies'].documents.create(
+  'id' => '124',
+  'company_name' => 'Stark Industries',
+  'num_employees' => 5215,
+  'country' => 'USA'
+)
+
+@typesense.collections['companies'].documents.create(
+  'id' => '127',
+  'company_name' => 'Stark Corp',
+  'num_employees' => 1031,
+  'country' => 'USA'
+)
+
+@typesense.collections['companies'].documents.create(
+  'id' => '125',
+  'company_name' => 'Acme Corp',
+  'num_employees' => 1002,
+  'country' => 'France'
+)
+
+@typesense.collections['companies'].documents.create(
+  'id' => '126',
+  'company_name' => 'Doofenshmirtz Inc',
+  'num_employees' => 2,
+  'country' => 'Tri-State Area'
+)
+
+##
+# Create overrides
+
+@typesense.collections['companies'].overrides.create(
+  "id": 'promote-doofenshmirtz',
+  "rule": {
+    "query": 'doofen',
+    "match": 'exact'
+  },
+  "includes": [{ 'id' => '126', 'position' => 1 }]
+)
+@typesense.collections['companies'].overrides.create(
+  "id": 'promote-acme',
+  "rule": {
+    "query": 'stark',
+    "match": 'exact'
+  },
+  "includes": [{ 'id' => '125', 'position' => 1 }]
+)
+
+##
+# Search for documents
+results = @typesense.collections['companies'].documents.search(
+  'q' => 'doofen',
+  'query_by' => 'company_name'
+)
+ap results
+
+results = @typesense.collections['companies'].documents.search(
+  'q' => 'stark',
+  'query_by' => 'company_name'
+)
+ap results
+
+results = @typesense.collections['companies'].documents.search(
+  'q' => 'Inc',
+  'query_by' => 'company_name',
+  'filter_by' => 'num_employees:<100',
+  'sort_by' => 'num_employees:desc'
+)
+ap results
+
+##
+# Cleanup
+# Drop the collection
+@typesense.collections['companies'].delete