weaviate-ruby 0.9.1 → 0.10.0

data/lib/weaviate/error.rb

@@ -3,4 +3,56 @@
 module Weaviate
   class Error < StandardError
   end
+
+  # Raised when Weaviate cannot be reached
+  class ConnectionFailed < Error
+  end
+
+  # Raised when a request times out
+  class TimeoutError < ConnectionFailed
+  end
+
+  # Raised when Weaviate responds with a 4xx or 5xx status
+  class HTTPError < Error
+    attr_reader :response
+
+    def initialize(message = nil, response: nil)
+      @response = response
+      super(message || "the server responded with status #{response&.status}")
+    end
+
+    def status
+      response&.status
+    end
+
+    def body
+      response&.body
+    end
+  end
+
+  class ClientError < HTTPError; end
+
+  class BadRequestError < ClientError; end
+
+  class UnauthorizedError < ClientError; end
+
+  class ForbiddenError < ClientError; end
+
+  class ResourceNotFound < ClientError; end
+
+  class ConflictError < ClientError; end
+
+  class UnprocessableEntityError < ClientError; end
+
+  class ServerError < HTTPError; end
+
+  # Raised when a GraphQL query returns errors
+  class GraphQLError < Error
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = errors
+      super(errors.map { |e| e["message"] }.join(", "))
+    end
+  end
 end

data/lib/weaviate/graphql.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Weaviate
+  class GraphQL < Base
+    PATH = "graphql"
+
+    # Execute a GraphQL query and return the "data" portion of the response.
+    def execute(query)
+      response = client.connection.post(PATH) do |req|
+        req.body = {query: query}
+      end
+
+      errors = response.body["errors"]
+      raise Weaviate::GraphQLError.new(errors) if errors && !errors.empty?
+
+      response.body["data"]
+    end
+  end
+end

data/lib/weaviate/groups.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Weaviate
+  # Manage roles of OIDC groups. Requires RBAC and OIDC to be enabled.
+  class Groups < Base
+    PATH = "authz/groups"
+    GROUP_TYPE = "oidc"
+
+    # Groups that have roles assigned.
+    def list
+      response = client.connection.get("#{PATH}/#{GROUP_TYPE}")
+      response.body
+    end
+
+    def roles(group_id:, include_full_roles: nil)
+      response = client.connection.get("#{PATH}/#{group_id}/roles/#{GROUP_TYPE}") do |req|
+        req.params["includeFullRoles"] = include_full_roles unless include_full_roles.nil?
+      end
+      response.body
+    end
+
+    def assign_roles(group_id:, roles:)
+      update_roles(group_id, "assign", roles)
+    end
+
+    def revoke_roles(group_id:, roles:)
+      update_roles(group_id, "revoke", roles)
+    end
+
+    private
+
+    def update_roles(group_id, action, roles)
+      response = client.connection.post("#{PATH}/#{group_id}/#{action}") do |req|
+        req.body = {roles: Array(roles), groupType: GROUP_TYPE}
+      end
+      response.success?
+    end
+  end
+end

data/lib/weaviate/health.rb

@@ -4,14 +4,23 @@ module Weaviate
   class Health < Base
     PATH = ".well-known"
 
+    # Whether Weaviate is alive. Returns false when it responds with an error or cannot be reached.
     def live?
-      response = client.connection.get("#{PATH}/live")
-      response.status == 200
+      check("#{PATH}/live")
     end
 
+    # Whether Weaviate is ready to receive traffic. Returns false when it responds with an error
+    # (e.g. 503 while starting up) or cannot be reached.
     def ready?
-      response = client.connection.get("#{PATH}/ready")
-      response.status == 200
+      check("#{PATH}/ready")
+    end
+
+    private
+
+    def check(path)
+      client.connection.get(path).status == 200
+    rescue Weaviate::HTTPError, Weaviate::ConnectionFailed
+      false
     end
   end
 end

data/lib/weaviate/nodes.rb

@@ -4,8 +4,16 @@ module Weaviate
   class Nodes < Base
     PATH = "nodes"
 
-    def list
-      response = client.connection.get(PATH)
+    # @param output [String] "minimal" (default) or "verbose", which includes shard details
+    # @param class_name [String] Only return shards of this collection
+    # @param shard_name [String] Only return this shard, requires class_name
+    def list(output: nil, class_name: nil, shard_name: nil)
+      path = class_name.nil? ? PATH : "#{PATH}/#{class_name}"
+
+      response = client.connection.get(path) do |req|
+        req.params["output"] = output unless output.nil?
+        req.params["shardName"] = shard_name unless shard_name.nil?
+      end
       response.body
     end
   end

data/lib/weaviate/objects.rb

@@ -66,10 +66,12 @@ module Weaviate
     )
       validate_consistency_level!(consistency_level) unless consistency_level.nil?
 
+      # Weaviate expects the tenant on each object rather than on the batch
+      objects = objects.map { |object| {tenant: tenant}.merge(object) } unless tenant.nil?
+
       response = client.connection.post("batch/#{PATH}") do |req|
         req.params["consistency_level"] = consistency_level.to_s.upcase unless consistency_level.nil?
         req.body = {objects: objects}
-        req.body["tenant"] = tenant unless tenant.nil?
       end
 
       response.body
@@ -109,6 +111,8 @@ module Weaviate
       end
 
       response.status == 204
+    rescue Weaviate::ResourceNotFound
+      false
     end
 
     # Update an individual data object based on its uuid.
@@ -175,11 +179,7 @@ module Weaviate
         req.params["tenant"] = tenant unless tenant.nil?
       end
 
-      if response.success?
-        response.body.empty?
-      else
-        response.body
-      end
+      response.body.empty?
     end
 
     def batch_delete(
@@ -212,6 +212,92 @@ module Weaviate
       response.body
     end
 
+    # Add a reference to an object's reference property.
+    def add_reference(
+      class_name:,
+      id:,
+      property:,
+      to_class_name:,
+      to_id:,
+      tenant: nil,
+      consistency_level: nil
+    )
+      validate_consistency_level!(consistency_level) unless consistency_level.nil?
+
+      response = client.connection.post(reference_path(class_name, id, property)) do |req|
+        req.params["consistency_level"] = consistency_level.to_s.upcase unless consistency_level.nil?
+        req.params["tenant"] = tenant unless tenant.nil?
+        req.body = {beacon: beacon(to_class_name, to_id)}
+      end
+
+      response.success?
+    end
+
+    # Replace all references of an object's reference property.
+    # @param to [Array<Hash>] The objects to reference, e.g. [{ class_name: "Category", id: "..." }]
+    def replace_references(
+      class_name:,
+      id:,
+      property:,
+      to:,
+      tenant: nil,
+      consistency_level: nil
+    )
+      validate_consistency_level!(consistency_level) unless consistency_level.nil?
+
+      response = client.connection.put(reference_path(class_name, id, property)) do |req|
+        req.params["consistency_level"] = consistency_level.to_s.upcase unless consistency_level.nil?
+        req.params["tenant"] = tenant unless tenant.nil?
+        req.body = to.map { |ref| {beacon: beacon(ref.fetch(:class_name), ref.fetch(:id))} }
+      end
+
+      response.success?
+    end
+
+    # Delete a reference from an object's reference property.
+    def delete_reference(
+      class_name:,
+      id:,
+      property:,
+      to_class_name:,
+      to_id:,
+      tenant: nil,
+      consistency_level: nil
+    )
+      validate_consistency_level!(consistency_level) unless consistency_level.nil?
+
+      response = client.connection.delete(reference_path(class_name, id, property)) do |req|
+        req.params["consistency_level"] = consistency_level.to_s.upcase unless consistency_level.nil?
+        req.params["tenant"] = tenant unless tenant.nil?
+        req.body = {beacon: beacon(to_class_name, to_id)}
+      end
+
+      response.success?
+    end
+
+    # Batch create references.
+    # @param references [Array<Hash>] e.g. [{ from_class_name: "Post", from_id: "...", property: "ofCategory", to_class_name: "Category", to_id: "...", tenant: nil }]
+    def batch_create_references(
+      references:,
+      consistency_level: nil
+    )
+      validate_consistency_level!(consistency_level) unless consistency_level.nil?
+
+      response = client.connection.post("batch/references") do |req|
+        req.params["consistency_level"] = consistency_level.to_s.upcase unless consistency_level.nil?
+        req.body = references.map do |ref|
+          body = {
+            from: "#{beacon(ref.fetch(:from_class_name), ref.fetch(:from_id))}/#{ref.fetch(:property)}",
+            to: beacon(ref.fetch(:to_class_name), ref.fetch(:to_id))
+          }
+          body[:tenant] = ref[:tenant] unless ref[:tenant].nil?
+          body
+        end
+      end
+
+      response.body
+    end
+
     # Validate a data object
     def validate(
       class_name:,
@@ -225,15 +311,19 @@ module Weaviate
         req.body["id"] = id unless id.nil?
       end
 
-      if response.success?
-        response.body.empty?
-      else
-        response.body
-      end
+      response.body.empty?
     end
 
     private
 
+    def reference_path(class_name, id, property)
+      "#{PATH}/#{class_name}/#{id}/references/#{property}"
+    end
+
+    def beacon(class_name, id)
+      "weaviate://localhost/#{class_name}/#{id}"
+    end
+
     def validate_consistency_level!(consistency_level)
       unless %w[ONE QUORUM ALL].include?(consistency_level.to_s.upcase)
         raise ArgumentError, 'consistency_level must be either "ONE" or "QUORUM" OR "ALL"'

data/lib/weaviate/query.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Weaviate
   class Query < Base
+    # Fields whose values are GraphQL enums, so strings are sent unquoted, e.g. operator: "Equal"
+    ENUM_KEYS = %w[operator order fusionType].freeze
+
+    GRAPHQL_NAME = /\A[_A-Za-z][_0-9A-Za-z]*\z/
+
     def get(
       class_name:,
       fields:,
@@ -18,14 +25,18 @@ module Weaviate
       near_object: nil,
       with_hybrid: nil,
       bm25: nil,
-      ask: nil
+      ask: nil,
+      group_by: nil
     )
-      response = client.graphql.execute(
+      data = client.graphql.execute(
         get_query(
           class_name: class_name,
-          tenant: tenant,
           fields: fields,
+          after: after,
+          tenant: tenant,
+          limit: limit,
           autocut: autocut,
+          offset: offset,
           sort: sort,
           where: where,
           near_text: near_text,
@@ -34,15 +45,11 @@ module Weaviate
           near_object: near_object,
           with_hybrid: with_hybrid,
           bm25: bm25,
-          ask: ask
-        ),
-        after: after,
-        limit: limit,
-        offset: offset
+          ask: ask,
+          group_by: group_by
+        )
       )
-      response.original_hash.dig("data", "Get", class_name)
-    rescue Graphlient::Errors::ExecutionError => error
-      raise Weaviate::Error.new(error.response.data.get.errors.messages.to_h)
+      data.dig("Get", class_name)
     end
 
     def aggs(
@@ -55,27 +62,30 @@ module Weaviate
       near_vector: nil,
       near_image: nil,
       near_object: nil,
-      group_by: nil
+      group_by: nil,
+      limit: nil,
+      with_hybrid: nil
     )
-      response = client.graphql.execute(
+      data = client.graphql.execute(
         aggs_query(
           class_name: class_name,
-          tenant: tenant,
           fields: fields,
+          tenant: tenant,
           where: where,
+          object_limit: object_limit,
           near_text: near_text,
           near_vector: near_vector,
           near_image: near_image,
-          near_object: near_object
-        ),
-        group_by: group_by,
-        object_limit: object_limit
+          near_object: near_object,
+          group_by: group_by,
+          limit: limit,
+          with_hybrid: with_hybrid
+        )
       )
-      response.original_hash.dig("data", "Aggregate", class_name)
-    rescue Graphlient::Errors::ExecutionError => error
-      raise Weaviate::Error.new(error.response.data.aggregate.errors.messages.to_h)
+      data.dig("Aggregate", class_name)
     end
 
+    # @deprecated Weaviate disables Explore when more than one vectorizer module is enabled.
     def explore(
       fields:,
       after: nil,
@@ -88,29 +98,35 @@ module Weaviate
       near_image: nil,
       near_object: nil
     )
-      response = client.graphql.execute(
+      unless @explore_deprecation_warned
+        warn "[weaviate-ruby] query.explore is deprecated: Weaviate disables Explore when more than one vectorizer module is enabled, " \
+          "which is the default on recent versions and on Weaviate Cloud. Use query.get on each collection instead."
+        @explore_deprecation_warned = true
+      end
+
+      # `after` is accepted for backwards compatibility, but Explore does not support it
+      data = client.graphql.execute(
         explore_query(
           fields: fields,
+          limit: limit,
+          offset: offset,
           sort: sort,
           where: where,
           near_text: near_text,
           near_vector: near_vector,
           near_image: near_image,
           near_object: near_object
-        ),
-        after: after,
-        limit: limit,
-        offset: offset
+        )
       )
-      response.original_hash.dig("data", "Explore")
-    rescue Graphlient::Errors::ExecutionError => error
-      raise Weaviate::Error.new(error.to_s)
+      data["Explore"]
     end
 
     private
 
     def explore_query(
       fields:,
+      limit: nil,
+      offset: nil,
       where: nil,
       near_text: nil,
       near_vector: nil,
@@ -118,21 +134,20 @@ module Weaviate
       near_object: nil,
       sort: nil
     )
-      client.graphql.parse <<~GRAPHQL
-        query(
-          $limit: Int,
-          $offset: Int
-        ) {
-          Explore (
-            limit: $limit,
-            offset: $offset,
-            #{(!near_text.nil?) ? "nearText: #{near_text}" : ""},
-            #{(!near_vector.nil?) ? "nearVector: #{near_vector}" : ""},
-            #{(!near_image.nil?) ? "nearImage: #{near_image}" : ""},
-            #{(!near_object.nil?) ? "nearObject: #{near_object}" : ""},
-            #{(!where.nil?) ? "where: #{where}" : ""},
-            #{(!sort.nil?) ? "sort: #{sort}" : ""}
-          ) {
+      arguments = build_arguments(
+        limit: integer_value(limit),
+        offset: integer_value(offset),
+        nearText: near_text,
+        nearVector: near_vector,
+        nearImage: near_image,
+        nearObject: near_object,
+        where: where,
+        sort: sort
+      )
+
+      <<~GRAPHQL
+        {
+          Explore#{arguments} {
             #{fields}
           }
         }
@@ -142,8 +157,11 @@ module Weaviate
     def get_query(
       class_name:,
       fields:,
-      autocut: nil,
+      after: nil,
       tenant: nil,
+      limit: nil,
+      autocut: nil,
+      offset: nil,
       where: nil,
       near_text: nil,
       near_vector: nil,
@@ -152,31 +170,31 @@ module Weaviate
       with_hybrid: nil,
       bm25: nil,
       ask: nil,
-      sort: nil
+      sort: nil,
+      group_by: nil
     )
-      client.graphql.parse <<~GRAPHQL
-        query(
-          $after: String,
-          $limit: Int,
-          $offset: Int,
-        ) {
+      arguments = build_arguments(
+        after: string_value(after),
+        limit: integer_value(limit),
+        offset: integer_value(offset),
+        autocut: integer_value(autocut),
+        tenant: string_value(tenant),
+        nearText: near_text,
+        nearVector: near_vector,
+        nearImage: near_image,
+        nearObject: near_object,
+        hybrid: with_hybrid,
+        bm25: bm25,
+        ask: ask,
+        where: where,
+        sort: sort,
+        groupBy: group_by
+      )
+
+      <<~GRAPHQL
+        {
           Get {
-            #{class_name}(
-              after: $after,
-              limit: $limit,
-              offset: $offset,
-              #{(!autocut.nil?) ? "autocut: #{autocut}" : ""},
-              #{(!tenant.nil?) ? "tenant: \"#{tenant}\"" : ""},
-              #{(!near_text.nil?) ? "nearText: #{near_text}" : ""},
-              #{(!near_vector.nil?) ? "nearVector: #{near_vector}" : ""},
-              #{(!near_image.nil?) ? "nearImage: #{near_image}" : ""},
-              #{(!near_object.nil?) ? "nearObject: #{near_object}" : ""},
-              #{(!with_hybrid.nil?) ? "hybrid: #{with_hybrid}" : ""},
-              #{(!bm25.nil?) ? "bm25: #{bm25}" : ""},
-              #{(!ask.nil?) ? "ask: #{ask}" : ""},
-              #{(!where.nil?) ? "where: #{where}" : ""},
-              #{(!sort.nil?) ? "sort: #{sort}" : ""}
-            ) {
+            #{class_name}#{arguments} {
               #{fields}
             }
           }
@@ -189,32 +207,88 @@ module Weaviate
       fields:,
       tenant: nil,
       where: nil,
+      object_limit: nil,
       near_text: nil,
       near_vector: nil,
       near_image: nil,
-      near_object: nil
+      near_object: nil,
+      group_by: nil,
+      limit: nil,
+      with_hybrid: nil
     )
-      client.graphql.parse <<~GRAPHQL
-        query(
-          $group_by: [String],
-          $object_limit: Int,
-        ) {
+      arguments = build_arguments(
+        objectLimit: integer_value(object_limit),
+        limit: integer_value(limit),
+        groupBy: group_by && Array(group_by).map(&:to_s).to_json,
+        tenant: string_value(tenant),
+        nearText: near_text,
+        nearVector: near_vector,
+        nearImage: near_image,
+        nearObject: near_object,
+        hybrid: with_hybrid,
+        where: where
+      )
+
+      <<~GRAPHQL
+        {
           Aggregate {
-            #{class_name}(
-              objectLimit: $object_limit,
-              groupBy: $group_by,
-              #{(!tenant.nil?) ? "tenant: \"#{tenant}\"" : ""},
-              #{(!near_text.nil?) ? "nearText: #{near_text}" : ""},
-              #{(!near_vector.nil?) ? "nearVector: #{near_vector}" : ""},
-              #{(!near_image.nil?) ? "nearImage: #{near_image}" : ""},
-              #{(!near_object.nil?) ? "nearObject: #{near_object}" : ""},
-              #{(!where.nil?) ? "where: #{where}" : ""}
-            ) {
+            #{class_name}#{arguments} {
               #{fields}
             }
           }
         }
       GRAPHQL
     end
+
+    # Only arguments that were provided are included in the query.
+    # Weaviate fails on explicit nulls, e.g. "interface conversion: interface {} is nil, not int".
+    # String arguments are passed through as raw GraphQL, anything else is serialized with {#graphql_value}.
+    def build_arguments(**arguments)
+      arguments = arguments.reject { |_, value| value.nil? }
+      return "" if arguments.empty?
+
+      arguments = arguments.map do |name, value|
+        "#{name}: #{value.is_a?(String) ? value : graphql_value(value)}"
+      end
+
+      "(#{arguments.join(", ")})"
+    end
+
+    # Serializes a Ruby value into a GraphQL input value:
+    #   { path: ["category"], operator: :Equal, valueText: "SCIENCE" }
+    #   => { path: ["category"], operator: Equal, valueText: "SCIENCE" }
+    # Strings are quoted and escaped, symbols become enums.
+    def graphql_value(value, key = nil)
+      case value
+      when Hash
+        "{ #{value.map { |k, v| "#{graphql_name(k)}: #{graphql_value(v, k.to_s)}" }.join(", ")} }"
+      when Array
+        "[#{value.map { |v| graphql_value(v, key) }.join(", ")}]"
+      when Symbol
+        graphql_name(value)
+      when String
+        (ENUM_KEYS.include?(key) && value.match?(GRAPHQL_NAME)) ? value : value.to_json
+      when Numeric, true, false
+        value.to_s
+      when nil
+        "null"
+      else
+        raise ArgumentError, "Cannot convert #{value.class} to a GraphQL value"
+      end
+    end
+
+    def graphql_name(name)
+      name = name.to_s
+      raise ArgumentError, "Invalid GraphQL name: #{name.inspect}" unless name.match?(GRAPHQL_NAME)
+      name
+    end
+
+    def integer_value(value)
+      Integer(value) unless value.nil?
+    end
+
+    def string_value(value)
+      value.to_s.to_json unless value.nil?
+    end
   end
 end