diff --git a/docs/reference/associations.txt b/docs/reference/associations.txt
index b2ca1117..9aedbeed 100644
--- a/docs/reference/associations.txt
+++ b/docs/reference/associations.txt
@@ -12,6 +12,329 @@ Associations
    :depth: 2
    :class: singlecol
 
+Embedded Associations
+=====================
+
+CouchbaseOrm supports embedding documents within a parent document using
+``embeds_one`` and ``embeds_many``. Unlike referenced associations, embedded
+documents are stored directly within the parent document and do not have their
+own separate document ID in the database. This is useful for modeling
+has-one and has-many relationships where the child documents don't need to exist
+independently.
+
+Embeds One
+----------
+
+Use the ``embeds_one`` association to declare that the parent embeds a single
+child document:
+
+.. code-block:: ruby
+
+  class Profile < CouchbaseOrm::Base
+    attribute :bio, :string
+    attribute :website, :string
+  end
+
+  class User < CouchbaseOrm::Base
+    attribute :name, :string
+    embeds_one :profile
+  end
+
+  user = User.create!(name: 'Alice', profile: { bio: 'Software Engineer' })
+  # => #<User _id: "user::123", name: "Alice", profile: {...}>
+
+  user.profile
+  # => #<Profile bio: "Software Engineer", website: nil>
+
+  user.profile.bio = 'Senior Software Engineer'
+  user.profile = user.profile  # Reassign to track changes
+  user.save!
+
+The embedded document is stored as a hash within the parent:
+
+.. code-block:: ruby
+
+  # In the database, the document looks like:
+  {
+    "_id": "user::123",
+    "name": "Alice",
+    "profile": {
+      "bio": "Software Engineer",
+      "website": null
+    }
+  }
+
+Embedded documents cannot be saved, destroyed, or reloaded independently:
+
+.. code-block:: ruby
+
+  user.profile.save
+  # => raises "Cannot save an embedded document!"
+
+Embeds Many
+-----------
+
+Use the ``embeds_many`` association to declare that the parent embeds multiple
+child documents:
+
+.. code-block:: ruby
+
+  class Address < CouchbaseOrm::Base
+    attribute :street, :string
+    attribute :city, :string
+  end
+
+  class Person < CouchbaseOrm::Base
+    attribute :name, :string
+    embeds_many :addresses
+  end
+
+  person = Person.create!(
+    name: 'Bob',
+    addresses: [
+      { street: '123 Main St', city: 'New York' },
+      { street: '456 Elm St', city: 'Boston' }
+    ]
+  )
+
+  person.addresses
+  # => [#<Address street: "123 Main St", city: "New York">,
+  #     #<Address street: "456 Elm St", city: "Boston">]
+
+  person.addresses << Address.new(street: '789 Oak Ave', city: 'Chicago')
+  person.addresses = person.addresses  # Reassign to track changes
+  person.save!
+
+Polymorphic Embedded Associations
+----------------------------------
+
+Both ``embeds_one`` and ``embeds_many`` support polymorphic associations,
+allowing you to embed different types of documents in the same association:
+
+.. code-block:: ruby
+
+  class Image < CouchbaseOrm::Base
+    attribute :url, :string
+    attribute :caption, :string
+  end
+
+  class Video < CouchbaseOrm::Base
+    attribute :url, :string
+    attribute :duration, :integer
+  end
+
+  class Post < CouchbaseOrm::Base
+    embeds_one :media, polymorphic: true
+  end
+
+  # Embed an image using an object
+  post = Post.create!(media: Image.new(url: 'photo.jpg', caption: 'Sunset'))
+  post.media
+  # => #<Image url: "photo.jpg", caption: "Sunset">
+
+  # Or use a hash with type key (snake_case class name)
+  post = Post.create!(media: { type: 'image', url: 'photo.jpg', caption: 'Sunset' })
+
+  # Switch to a video
+  post.media = Video.new(url: 'clip.mp4', duration: 120)
+  post.save!
+
+For ``embeds_many`` with polymorphism:
+
+.. code-block:: ruby
+
+  class Article < CouchbaseOrm::Base
+    embeds_many :attachments, polymorphic: true
+  end
+
+  # Using objects
+  article = Article.create!(
+    attachments: [
+      Image.new(url: 'diagram.png', caption: 'Architecture'),
+      Video.new(url: 'demo.mp4', duration: 90)
+    ]
+  )
+
+  # Or using hashes with type key (snake_case class names)
+  article = Article.create!(
+    attachments: [
+      { type: 'image', url: 'diagram.png', caption: 'Architecture' },
+      { type: 'video', url: 'demo.mp4', duration: 90 }
+    ]
+  )
+
+  article.attachments
+  # => [#<Image ...>, #<Video ...>]
+
+When using polymorphic embedded associations, the type information is stored
+inside each embedded document as a ``type`` field. For example:
+
+.. code-block:: json
+
+  {
+    "_id": "post::123",
+    "media": {
+      "type": "Image",
+      "url": "photo.jpg",
+      "caption": "Sunset"
+    }
+  }
+
+**Note**: When using hashes with polymorphic associations, you must include
+the ``type`` key (either as a symbol ``:type`` or string ``'type'``) with
+the snake_case version of the class name. For example, use ``'image'`` for
+the ``Image`` class or ``'video_attachment'`` for the ``VideoAttachment`` class.
+Without it, an ``ArgumentError`` will be raised.
+
+Restricting Polymorphic Types
+------------------------------
+
+You can restrict which types are allowed in a polymorphic association by
+passing an array of allowed class names to the ``polymorphic`` parameter:
+
+.. code-block:: ruby
+
+  class Post < CouchbaseOrm::Base
+    # Only Image and Video are allowed
+    embeds_one :media, polymorphic: ['Image', 'Video']
+  end
+
+  class Article < CouchbaseOrm::Base
+    # Only specific attachment types allowed
+    embeds_many :attachments, polymorphic: ['ImageAttachment', 'VideoAttachment']
+  end
+
+  # This works
+  post = Post.new(media: Image.new(url: 'photo.jpg'))
+  post.valid?
+  # => true
+
+  # This raises a validation error
+  post = Post.new(media: Audio.new(url: 'song.mp3'))
+  post.valid?
+  # => false
+  post.errors[:media]
+  # => ["Audio is not an allowed type. Allowed types: Image, Video"]
+
+You can use snake_case names in the array, which will be automatically
+converted to CamelCase class names:
+
+.. code-block:: ruby
+
+  class Post < CouchbaseOrm::Base
+    embeds_one :media, polymorphic: [:image, 'video']  # Same as ['Image', 'Video']
+  end
+
+**Polymorphic Type Validator**: When type restrictions are specified, CouchbaseOrm
+automatically adds a ``PolymorphicTypeValidator`` to ensure that only allowed types
+can be assigned to the association. The validator:
+
+- Validates both single objects (``embeds_one``) and arrays (``embeds_many``)
+- Provides clear error messages listing the allowed types
+- Skips validation when no type restrictions are set or the value is nil
+- Runs during normal model validation (``valid?``, ``save``, ``create``, etc.)
+
+For ``embeds_many`` associations with type restrictions, each item in the array
+is validated individually:
+
+.. code-block:: ruby
+
+  class Article < CouchbaseOrm::Base
+    embeds_many :attachments, polymorphic: ['Image', 'Video']
+  end
+
+  article = Article.new(
+    attachments: [
+      Image.new(url: 'photo.jpg'),
+      Audio.new(url: 'song.mp3')  # Not allowed!
+    ]
+  )
+  
+  article.valid?
+  # => false
+  article.errors[:attachments]
+  # => ["item #1 (Audio) is not an allowed type. Allowed types: Image, Video"]
+
+Custom Storage Keys
+-------------------
+
+Use the ``store_as`` option to specify a different attribute name for storage:
+
+.. code-block:: ruby
+
+  class User < CouchbaseOrm::Base
+    embeds_one :profile, store_as: 'p'
+    embeds_many :addresses, store_as: 'addrs'
+  end
+
+  # In the database:
+  {
+    "_id": "user::123",
+    "p": { "bio": "..." },
+    "addrs": [{ "street": "..." }]
+  }
+
+Embedded Association Validation
+--------------------------------
+
+By default, embedded associations are validated when the parent is validated.
+You can disable this with ``validate: false``:
+
+.. code-block:: ruby
+
+  class Profile < CouchbaseOrm::Base
+    attribute :bio, :string
+    validates :bio, presence: true
+  end
+
+  class User < CouchbaseOrm::Base
+    embeds_one :profile
+  end
+
+  user = User.new(profile: { bio: nil })
+  user.valid?
+  # => false
+  user.errors[:profile]
+  # => ["is invalid"]
+
+  # To disable validation:
+  class User < CouchbaseOrm::Base
+    embeds_one :profile, validate: false
+  end
+
+Custom Class Names
+------------------
+
+Specify a different class name for embedded associations when the class cannot
+be inferred from the association name:
+
+.. code-block:: ruby
+
+  class User < CouchbaseOrm::Base
+    embeds_one :bio, class_name: 'Profile'
+    embeds_many :locations, class_name: 'Address'
+  end
+
+Key Differences from Referenced Associations
+---------------------------------------------
+
+Embedded associations differ from referenced associations in several ways:
+
+- **Storage**: Embedded documents are stored within the parent document, not as
+  separate documents in the database.
+
+- **Lifecycle**: Embedded documents cannot be saved, updated, or destroyed
+  independently. They are always saved as part of the parent document.
+
+- **Performance**: Reading a parent document also loads all embedded documents
+  in a single operation, which can be more efficient than separate queries.
+
+- **Querying**: Embedded documents cannot be queried independently. You must
+  query the parent document and then access the embedded documents.
+
+- **Identity**: Embedded documents do not have their own document ID by default
+  (the ``id`` field is removed when embedding).
+
 Referenced Associations
 =======================
 
diff --git a/lib/couchbase-orm.rb b/lib/couchbase-orm.rb
index 71d0fd12..310bfc79 100644
--- a/lib/couchbase-orm.rb
+++ b/lib/couchbase-orm.rb
@@ -22,6 +22,7 @@ module CouchbaseOrm
   autoload :EmbedsOne, 'couchbase-orm/utilities/embeds_one'
   autoload :EmbedsMany, 'couchbase-orm/utilities/embeds_many'
   autoload :EmbeddedAssociatedValidator, 'couchbase-orm/validators/embedded_associated_validator'
+  autoload :PolymorphicTypeValidator, 'couchbase-orm/validators/polymorphic_type_validator'
 
   # if COUCHBASE_ORM_DEBUG environement variable exist then logger is set to Logger::DEBUG level
   # else logger is set to Logger::INFO level
diff --git a/lib/couchbase-orm/utilities/embeds_many.rb b/lib/couchbase-orm/utilities/embeds_many.rb
index 2dbb7d41..f0527aba 100644
--- a/lib/couchbase-orm/utilities/embeds_many.rb
+++ b/lib/couchbase-orm/utilities/embeds_many.rb
@@ -2,24 +2,107 @@
 
 module CouchbaseOrm
   module EmbedsMany
-    def embeds_many(name, class_name: nil, store_as: nil, validate: true)
+    def embeds_many(name, class_name: nil, store_as: nil, validate: true, polymorphic: false)
       storage_key = (store_as || name).to_sym
       attribute storage_key, :array, type: :hash, default: []
 
       instance_var = "@__assoc_#{name}"
       klass_name = (class_name || name.to_s.singularize.camelize)
 
+      # Handle polymorphic parameter: can be true, false, or array of allowed types
+      is_polymorphic = polymorphic.is_a?(Array) || polymorphic == true
+      allowed_types = polymorphic.is_a?(Array) ? polymorphic.map { |t| t.to_s.camelize } : nil
+
       set_embedded(name, {
         type: :many,
-        class_name: klass_name, # store as string, resolve later
+        class_name: klass_name,
         key: storage_key,
         name: name,
         instance_var: instance_var,
+        polymorphic: is_polymorphic,
+        allowed_types: allowed_types,
       })
 
-      validates_embedded(name) if validate
+      if validate
+        validates_embedded(name)
+        validates_with CouchbaseOrm::PolymorphicTypeValidator, attributes: [name], allowed_types: allowed_types if allowed_types.present?
+      end
+
+      if is_polymorphic
+        define_polymorphic_embeds_many_reader(name, storage_key, instance_var)
+        define_polymorphic_embeds_many_writer(name, storage_key, instance_var)
+      else
+        define_standard_embeds_many_reader(name, storage_key, instance_var, klass_name)
+        define_standard_embeds_many_writer(name, storage_key, instance_var, klass_name)
+      end
+
+      define_method(:"#{name}_reset") do
+        remove_instance_variable(instance_var) if instance_variable_defined?(instance_var)
+      end
+    end
+
+    private
+
+    def define_polymorphic_embeds_many_reader(name, storage_key, instance_var)
+      define_method(name) do
+        return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+
+        raw_array = read_attribute(storage_key)
+        embedded_objects = raw_array.map do |raw|
+          next unless raw.present?
+
+          type = raw['type'] || raw[:type]
+          next unless type.present?
+
+          klass = type.constantize
+          attrs = raw.dup
+          attrs.delete('type')
+          attrs.delete(:type)
+          obj = klass.new(attrs)
+          obj.embedded = true
+          obj
+        end.compact
+
+        instance_variable_set(instance_var, embedded_objects)
+      end
+    end
+
+    def define_polymorphic_embeds_many_writer(name, storage_key, instance_var)
+      define_method("#{name}=") do |val|
+        embedded_objects = []
+        serialized = []
+
+        Array(val).each do |v|
+          next if v.nil?
+
+          obj = if v.is_a?(Hash)
+                  type_name = v[:type] || v['type']
+                  raise ArgumentError.new("Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name.") unless type_name.present?
+
+                  klass = type_name.to_s.camelize.constantize
+                  attrs = v.dup
+                  attrs.delete(:type)
+                  attrs.delete('type')
+                  klass.new(attrs)
+                else
+                  v
+                end
+
+          obj.embedded = true
+          raw = obj.serialized_attributes
+          raw.delete('id') if raw['id'].blank?
+          raw['type'] = obj.class.name
+
+          embedded_objects << obj
+          serialized << raw
+        end
+
+        write_attribute(storage_key, serialized)
+        instance_variable_set(instance_var, embedded_objects)
+      end
+    end
 
-      # Lazy class resolution method
+    def define_standard_embeds_many_reader(name, storage_key, instance_var, klass_name)
       define_method("_resolve_embedded_class_for_#{name}") do
         @__resolved_classes ||= {}
         @__resolved_classes[name] ||= begin
@@ -42,7 +125,9 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true)
 
         instance_variable_set(instance_var, embedded_objects)
       end
+    end
 
+    def define_standard_embeds_many_writer(name, storage_key, instance_var, _klass_name)
       define_method("#{name}=") do |val|
         klass = send("_resolve_embedded_class_for_#{name}")
 
@@ -61,10 +146,6 @@ def embeds_many(name, class_name: nil, store_as: nil, validate: true)
         write_attribute(storage_key, serialized)
         instance_variable_set(instance_var, embedded_objects)
       end
-
-      define_method(:"#{name}_reset") do
-        remove_instance_variable(instance_var) if instance_variable_defined?(instance_var)
-      end
     end
   end
 end
diff --git a/lib/couchbase-orm/utilities/embeds_one.rb b/lib/couchbase-orm/utilities/embeds_one.rb
index e42aca64..dbf1b3fc 100644
--- a/lib/couchbase-orm/utilities/embeds_one.rb
+++ b/lib/couchbase-orm/utilities/embeds_one.rb
@@ -2,24 +2,99 @@
 
 module CouchbaseOrm
   module EmbedsOne
-    def embeds_one(name, class_name: nil, store_as: nil, validate: true)
+    def embeds_one(name, class_name: nil, store_as: nil, validate: true, polymorphic: false)
       storage_key = (store_as || name).to_sym
       attribute storage_key, :hash, default: nil
 
       instance_var = "@__assoc_#{name}"
       klass_name = (class_name || name.to_s.camelize)
 
+      # Handle polymorphic parameter: can be true, false, or array of allowed types
+      is_polymorphic = polymorphic.is_a?(Array) || polymorphic == true
+      allowed_types = polymorphic.is_a?(Array) ? polymorphic.map { |t| t.to_s.camelize } : nil
+
       set_embedded(name, {
         type: :one,
-        class_name: klass_name, # keep as string to delay resolution
+        class_name: klass_name,
         key: storage_key,
         name: name,
         instance_var: instance_var,
+        polymorphic: is_polymorphic,
+        allowed_types: allowed_types,
       })
 
-      validates_embedded(name) if validate
+      if validate
+        validates_embedded(name)
+        validates_with CouchbaseOrm::PolymorphicTypeValidator, attributes: [name], allowed_types: allowed_types if allowed_types.present?
+      end
+
+      if is_polymorphic
+        define_polymorphic_embeds_one_reader(name, storage_key, instance_var)
+        define_polymorphic_embeds_one_writer(name, storage_key, instance_var)
+      else
+        define_standard_embeds_one_reader(name, storage_key, instance_var, klass_name)
+        define_standard_embeds_one_writer(name, storage_key, instance_var, klass_name)
+      end
+
+      define_method(:"#{name}_reset") do
+        remove_instance_variable(instance_var) if instance_variable_defined?(instance_var)
+      end
+    end
+
+    private
+
+    def define_polymorphic_embeds_one_reader(name, storage_key, instance_var)
+      define_method(name) do
+        return instance_variable_get(instance_var) if instance_variable_defined?(instance_var)
+
+        raw = read_attribute(storage_key)
+        return instance_variable_set(instance_var, nil) unless raw.present?
+
+        type = raw['type'] || raw[:type]
+        return instance_variable_set(instance_var, nil) unless type.present?
+
+        klass = type.constantize
+        attrs = raw.dup
+        attrs.delete('type')
+        attrs.delete(:type)
+        obj = klass.new(attrs)
+        obj.embedded = true
+        instance_variable_set(instance_var, obj)
+      end
+    end
+
+    def define_polymorphic_embeds_one_writer(name, storage_key, instance_var)
+      define_method("#{name}=") do |val|
+        if val.nil?
+          write_attribute(storage_key, nil)
+          instance_variable_set(instance_var, nil)
+          return
+        end
+
+        obj = if val.is_a?(Hash)
+                type_name = val[:type] || val['type']
+                raise ArgumentError.new("Cannot infer type from Hash for polymorphic embeds_one. Include 'type' key with class name.") unless type_name.present?
+
+                klass = type_name.to_s.camelize.constantize
+                attrs = val.dup
+                attrs.delete(:type)
+                attrs.delete('type')
+                klass.new(attrs)
+              else
+                val
+              end
+
+        obj.embedded = true
+        raw = obj.serialized_attributes
+        raw.delete('id') if raw['id'].blank?
+        raw['type'] = obj.class.name
+
+        write_attribute(storage_key, raw)
+        instance_variable_set(instance_var, obj)
+      end
+    end
 
-      # Helper to lazy-resolve class when needed
+    def define_standard_embeds_one_reader(name, storage_key, instance_var, klass_name)
       define_method("_resolve_embedded_class_for_#{name}") do
         @__resolved_classes ||= {}
         @__resolved_classes[name] ||= begin
@@ -41,12 +116,14 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true)
         obj.embedded = true
         instance_variable_set(instance_var, obj)
       end
+    end
 
+    def define_standard_embeds_one_writer(name, storage_key, instance_var, _klass_name)
       define_method("#{name}=") do |val|
         if val.nil?
           write_attribute(storage_key, nil)
           instance_variable_set(instance_var, nil)
-          next
+          return
         end
 
         klass = send("_resolve_embedded_class_for_#{name}")
@@ -59,10 +136,6 @@ def embeds_one(name, class_name: nil, store_as: nil, validate: true)
         write_attribute(storage_key, raw)
         instance_variable_set(instance_var, obj)
       end
-
-      define_method(:"#{name}_reset") do
-        remove_instance_variable(instance_var) if instance_variable_defined?(instance_var)
-      end
     end
   end
 end
diff --git a/lib/couchbase-orm/validators/polymorphic_type_validator.rb b/lib/couchbase-orm/validators/polymorphic_type_validator.rb
new file mode 100644
index 00000000..521b76d5
--- /dev/null
+++ b/lib/couchbase-orm/validators/polymorphic_type_validator.rb
@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CouchbaseOrm
+  class PolymorphicTypeValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, value)
+      allowed_types = options[:allowed_types]
+      return if allowed_types.blank?
+      return if value.nil?
+
+      # Handle array of embedded objects
+      if value.is_a?(Array)
+        value.each_with_index do |obj, i|
+          next if obj.nil?
+          next if allowed_types.include?(obj.class.name)
+
+          record.errors.add(
+            attribute,
+            "item ##{i} (#{obj.class.name}) is not an allowed type. Allowed types: #{allowed_types.join(', ')}"
+          )
+        end
+      else
+        # Handle single embedded object
+        return if allowed_types.include?(value.class.name)
+
+        record.errors.add(
+          attribute,
+          "#{value.class.name} is not an allowed type. Allowed types: #{allowed_types.join(', ')}"
+        )
+      end
+    end
+  end
+end
diff --git a/spec/embeds_many_spec.rb b/spec/embeds_many_spec.rb
index d074e163..7fc13591 100644
--- a/spec/embeds_many_spec.rb
+++ b/spec/embeds_many_spec.rb
@@ -40,16 +40,16 @@ class BasePerson < CouchbaseOrm::Base
 class ChildPerson < BasePerson
 end
 
-class AddressBook < CouchbaseOrm::Base
-  attribute :label, :string
-  has_many :contacts, type: :n1ql, class_name: 'Contact'
-end
-
 class Contact < CouchbaseOrm::Base
   attribute :name, :string
   belongs_to :address_book
 end
 
+class AddressBook < CouchbaseOrm::Base
+  attribute :label, :string
+  has_many :contacts, type: :n1ql, class_name: 'Contact'
+end
+
 class PersonWithBook < CouchbaseOrm::Base
   embeds_many :address_books, class_name: 'AddressBook'
 end
@@ -67,6 +67,34 @@ class Citizen < CouchbaseOrm::Base
   embeds_many :addresses, class_name: 'AddressWithCity'
 end
 
+class ImageAttachment < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :caption, :string
+end
+
+class VideoAttachment < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :duration, :integer
+end
+
+class DocumentAttachment < CouchbaseOrm::Base
+  attribute :filename, :string
+  attribute :size, :integer
+end
+
+class AudioAttachment < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :bitrate, :integer
+end
+
+class Article < CouchbaseOrm::Base
+  embeds_many :attachments, polymorphic: true
+end
+
+class RestrictedArticle < CouchbaseOrm::Base
+  embeds_many :attachments, polymorphic: ['ImageAttachment', 'VideoAttachment']
+end
+
 describe CouchbaseOrm::EmbedsMany do
   let(:raw_data) { [{ street: '123 Main St' }, { street: '456 Elm St' }] }
 
@@ -354,4 +382,370 @@ class Citizen < CouchbaseOrm::Base
       person.destroy! if person&.persisted?
     end
   end
+
+  describe 'polymorphic embeds_many' do
+    it 'can embed different types polymorphically with types attribute' do
+      image = ImageAttachment.new(url: 'https://example.com/image.jpg', caption: 'A beautiful sunset')
+      video = VideoAttachment.new(url: 'https://example.com/video.mp4', duration: 120)
+      article = Article.new(attachments: [image, video])
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments.first).to be_a(ImageAttachment)
+      expect(article.attachments.first.url).to eq('https://example.com/image.jpg')
+      expect(article.attachments.first.caption).to eq('A beautiful sunset')
+      expect(article.attachments.last).to be_a(VideoAttachment)
+      expect(article.attachments.last.url).to eq('https://example.com/video.mp4')
+      expect(article.attachments.last.duration).to eq(120)
+      expect(article.attributes['attachments'].first['type']).to eq('ImageAttachment')
+      expect(article.attributes['attachments'].last['type']).to eq('VideoAttachment')
+    end
+
+    it 'can embed multiple items of the same polymorphic type' do
+      image1 = ImageAttachment.new(url: 'https://example.com/image1.jpg', caption: 'First')
+      image2 = ImageAttachment.new(url: 'https://example.com/image2.jpg', caption: 'Second')
+      article = Article.new(attachments: [image1, image2])
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments).to all(be_a(ImageAttachment))
+      expect(article.attachments.first.caption).to eq('First')
+      expect(article.attachments.last.caption).to eq('Second')
+      expect(article.attributes['attachments'].map { |a| a['type'] }).to eq(['ImageAttachment', 'ImageAttachment'])
+    end
+
+    it 'can embed mixed polymorphic types' do
+      image = ImageAttachment.new(url: 'https://example.com/pic.jpg', caption: 'Photo')
+      video = VideoAttachment.new(url: 'https://example.com/clip.mp4', duration: 90)
+      doc = DocumentAttachment.new(filename: 'report.pdf', size: 1024)
+      article = Article.new(attachments: [image, video, doc])
+
+      expect(article.attachments.size).to eq(3)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[2]).to be_a(DocumentAttachment)
+      expect(article.attachments[2].filename).to eq('report.pdf')
+      expect(article.attachments[2].size).to eq(1024)
+    end
+
+    it 'persists and retrieves polymorphic embedded collections correctly' do
+      image = ImageAttachment.new(url: 'https://example.com/demo.jpg', caption: 'Demo')
+      video = VideoAttachment.new(url: 'https://example.com/demo.mp4', duration: 60)
+      article = Article.create!(attachments: [image, video])
+
+      loaded = Article.find(article.id)
+      expect(loaded.attachments.size).to eq(2)
+      expect(loaded.attachments.first).to be_a(ImageAttachment)
+      expect(loaded.attachments.first.url).to eq('https://example.com/demo.jpg')
+      expect(loaded.attachments.last).to be_a(VideoAttachment)
+      expect(loaded.attachments.last.duration).to eq(60)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'can update polymorphic embedded collections' do
+      image = ImageAttachment.new(url: 'https://example.com/original.jpg', caption: 'Original')
+      article = Article.create!(attachments: [image])
+
+      video = VideoAttachment.new(url: 'https://example.com/new.mp4', duration: 45)
+      article.attachments = [video]
+      article.save!
+
+      article.reload
+      expect(article.attachments.size).to eq(1)
+      expect(article.attachments.first).to be_a(VideoAttachment)
+      expect(article.attachments.first.url).to eq('https://example.com/new.mp4')
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'can add to polymorphic embedded collection' do
+      image = ImageAttachment.new(url: 'https://example.com/first.jpg', caption: 'First')
+      article = Article.create!(attachments: [image])
+
+      video = VideoAttachment.new(url: 'https://example.com/second.mp4', duration: 30)
+      article.attachments = article.attachments + [video]
+      article.save!
+
+      article.reload
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments.first).to be_a(ImageAttachment)
+      expect(article.attachments.last).to be_a(VideoAttachment)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'sets embedded flag on polymorphic embedded objects' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      video = VideoAttachment.new(url: 'https://example.com/test.mp4', duration: 60)
+      article = Article.new(attachments: [image, video])
+
+      article.attachments.each do |attachment|
+        expect(attachment.instance_variable_get(:@_embedded)).to be true
+      end
+    end
+
+    it 'can set polymorphic embedded collection to empty array' do
+      video = VideoAttachment.new(url: 'https://example.com/test.mp4', duration: 60)
+      article = Article.new(attachments: [video])
+
+      article.attachments = []
+      expect(article.attachments).to eq([])
+      expect(article.attributes['attachments']).to eq([])
+    end
+
+    it 'can set polymorphic embedded collection to nil' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image])
+
+      article.attachments = nil
+      expect(article.attachments).to eq([])
+      expect(article.attributes['attachments']).to eq([])
+    end
+
+    it 'raises error when trying to assign Hash to polymorphic embeds_many' do
+      article = Article.new
+
+      expect {
+        article.attachments = [{ url: 'https://example.com/test.jpg', caption: 'Test' }]
+      }.to raise_error(ArgumentError, "Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name.")
+    end
+
+    it 'skips nil values in polymorphic embedded collection' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image, nil])
+
+      expect(article.attachments.size).to eq(1)
+      expect(article.attachments.first).to be_a(ImageAttachment)
+    end
+
+    it 'memoizes polymorphic embedded collection after first access' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image])
+
+      first_call = article.attachments
+      second_call = article.attachments
+
+      expect(first_call).to equal(second_call)
+    end
+
+    it 'lazily loads polymorphic embedded collection' do
+      image = ImageAttachment.new(url: 'https://example.com/lazy.jpg', caption: 'Lazy')
+      article = Article.create!(attachments: [image])
+      article = Article.find(article.id)
+
+      expect(article.instance_variable_defined?(:@__assoc_attachments)).to be false
+
+      _ = article.attachments
+
+      expect(article.instance_variable_defined?(:@__assoc_attachments)).to be true
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'supports reset for polymorphic embedded collection' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image])
+
+      original = article.attachments
+      article.attachments_reset
+
+      new_instance = article.attachments
+      expect(new_instance).to be_an(Array)
+      expect(new_instance).not_to equal(original)
+    end
+
+    it 'does not include id in polymorphic embedded objects if blank' do
+      image = ImageAttachment.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      article = Article.new(attachments: [image])
+
+      expect(article.send(:serialized_attributes)['attachments'].first).not_to include('id')
+    end
+
+    it 'handles empty polymorphic embedded collection on read' do
+      article = Article.new
+      expect(article.attachments).to eq([])
+    end
+
+    it 'preserves order of polymorphic embedded objects' do
+      video = VideoAttachment.new(url: 'https://example.com/first.mp4', duration: 30)
+      image = ImageAttachment.new(url: 'https://example.com/second.jpg', caption: 'Second')
+      doc = DocumentAttachment.new(filename: 'third.pdf', size: 2048)
+
+      article = Article.create!(attachments: [video, image, doc])
+      article.reload
+
+      expect(article.attachments[0]).to be_a(VideoAttachment)
+      expect(article.attachments[1]).to be_a(ImageAttachment)
+      expect(article.attachments[2]).to be_a(DocumentAttachment)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'accepts hashes with type key for polymorphic embeds_many' do
+      article = Article.new(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/hash1.jpg', caption: 'First' },
+          { type: 'video_attachment', url: 'https://example.com/hash2.mp4', duration: 45 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[0].url).to eq('https://example.com/hash1.jpg')
+      expect(article.attachments[0].caption).to eq('First')
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[1].url).to eq('https://example.com/hash2.mp4')
+      expect(article.attachments[1].duration).to eq(45)
+      expect(article.attributes['attachments'].map { |a| a['type'] }).to eq(['ImageAttachment', 'VideoAttachment'])
+    end
+
+    it 'accepts hashes with string type key for polymorphic embeds_many' do
+      article = Article.new(
+        attachments: [
+          { 'type' => 'document_attachment', 'filename' => 'doc.pdf', 'size' => 1024 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(1)
+      expect(article.attachments.first).to be_a(DocumentAttachment)
+      expect(article.attachments.first.filename).to eq('doc.pdf')
+      expect(article.attachments.first.size).to eq(1024)
+    end
+
+    it 'raises error when hash is missing type key for polymorphic embeds_many' do
+      expect {
+        Article.new(attachments: [{ url: 'https://example.com/no-type.jpg', caption: 'Missing Type' }])
+      }.to raise_error(ArgumentError, "Cannot infer type from Hash for polymorphic embeds_many. Include 'type' key with class name.")
+    end
+
+    it 'can mix objects and hashes with type key' do
+      image_obj = ImageAttachment.new(url: 'https://example.com/obj.jpg', caption: 'Object')
+      article = Article.new(
+        attachments: [
+          image_obj,
+          { type: 'video_attachment', url: 'https://example.com/hash.mp4', duration: 60 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[0].url).to eq('https://example.com/obj.jpg')
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[1].duration).to eq(60)
+    end
+
+    it 'persists and retrieves polymorphic embedded from hashes' do
+      article = Article.create!(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/persist.jpg', caption: 'Persisted' },
+          { type: 'video_attachment', url: 'https://example.com/persist.mp4', duration: 90 }
+        ]
+      )
+
+      loaded = Article.find(article.id)
+      expect(loaded.attachments.size).to eq(2)
+      expect(loaded.attachments[0]).to be_a(ImageAttachment)
+      expect(loaded.attachments[0].url).to eq('https://example.com/persist.jpg')
+      expect(loaded.attachments[1]).to be_a(VideoAttachment)
+      expect(loaded.attachments[1].duration).to eq(90)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+
+    it 'includes type in serialized attributes' do
+      article = Article.new(
+        attachments: [{ type: 'image_attachment', url: 'https://example.com/test.jpg', caption: 'Test' }]
+      )
+
+      serialized = article.send(:serialized_attributes)
+      expect(serialized['attachments'].first).to have_key('type')
+      expect(serialized['attachments'].first['type']).to eq('ImageAttachment')
+    end
+
+    it 'handles mixed valid and nil values with hashes' do
+      article = Article.new(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/test.jpg', caption: 'Test' },
+          nil,
+          { type: 'video_attachment', url: 'https://example.com/test.mp4', duration: 30 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+    end
+  end
+
+  describe 'polymorphic embeds_many with types restriction' do
+    it 'accepts allowed types with objects' do
+      image = ImageAttachment.new(url: 'https://example.com/allowed.jpg', caption: 'Allowed')
+      video = VideoAttachment.new(url: 'https://example.com/allowed.mp4', duration: 60)
+      article = RestrictedArticle.new(attachments: [image, video])
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[0].url).to eq('https://example.com/allowed.jpg')
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[1].url).to eq('https://example.com/allowed.mp4')
+    end
+
+    it 'accepts allowed types with hashes' do
+      article = RestrictedArticle.new(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/hash.jpg', caption: 'Hash' },
+          { type: 'video_attachment', url: 'https://example.com/hash.mp4', duration: 90 }
+        ]
+      )
+
+      expect(article.attachments.size).to eq(2)
+      expect(article.attachments[0]).to be_a(ImageAttachment)
+      expect(article.attachments[0].url).to eq('https://example.com/hash.jpg')
+      expect(article.attachments[1]).to be_a(VideoAttachment)
+      expect(article.attachments[1].duration).to eq(90)
+    end
+
+    it 'rejects disallowed types with objects' do
+      audio = AudioAttachment.new(url: 'https://example.com/denied.mp3', bitrate: 128)
+      article = RestrictedArticle.new(attachments: [audio])
+
+      expect(article).not_to be_valid
+      expect(article.errors[:attachments]).to include('item #0 (AudioAttachment) is not an allowed type. Allowed types: ImageAttachment, VideoAttachment')
+    end
+
+    it 'rejects disallowed types with hashes' do
+      article = RestrictedArticle.new(
+        attachments: [{ type: 'audio_attachment', url: 'https://example.com/denied.mp3', bitrate: 128 }]
+      )
+
+      expect(article).not_to be_valid
+      expect(article.errors[:attachments]).to include('item #0 (AudioAttachment) is not an allowed type. Allowed types: ImageAttachment, VideoAttachment')
+    end
+
+    it 'rejects disallowed types mixed with allowed types' do
+      image = ImageAttachment.new(url: 'https://example.com/allowed.jpg', caption: 'Allowed')
+      audio = AudioAttachment.new(url: 'https://example.com/denied.mp3', bitrate: 128)
+      article = RestrictedArticle.new(attachments: [image, audio])
+
+      expect(article).not_to be_valid
+      expect(article.errors[:attachments]).to include('item #1 (AudioAttachment) is not an allowed type. Allowed types: ImageAttachment, VideoAttachment')
+    end
+
+    it 'persists and retrieves with type restrictions' do
+      article = RestrictedArticle.create!(
+        attachments: [
+          { type: 'image_attachment', url: 'https://example.com/restricted.jpg', caption: 'Restricted' },
+          { type: 'video_attachment', url: 'https://example.com/restricted.mp4', duration: 120 }
+        ]
+      )
+
+      loaded = RestrictedArticle.find(article.id)
+      expect(loaded.attachments.size).to eq(2)
+      expect(loaded.attachments[0]).to be_a(ImageAttachment)
+      expect(loaded.attachments[0].url).to eq('https://example.com/restricted.jpg')
+      expect(loaded.attachments[1]).to be_a(VideoAttachment)
+      expect(loaded.attachments[1].duration).to eq(120)
+    ensure
+      article.destroy! if article&.persisted?
+    end
+  end
 end
diff --git a/spec/embeds_one_spec.rb b/spec/embeds_one_spec.rb
index a72d08bb..04595767 100644
--- a/spec/embeds_one_spec.rb
+++ b/spec/embeds_one_spec.rb
@@ -66,6 +66,36 @@ class Article < CouchbaseOrm::Base
   embeds_one :comments_container, class_name: 'CommentsContainer'
 end
 
+class Attachment < CouchbaseOrm::Base
+  attribute :filename, :string
+  attribute :attachable_type, :string
+  attribute :attachable_id, :string
+  belongs_to :attachable, polymorphic: true
+end
+
+class Image < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :caption, :string
+end
+
+class Video < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :duration, :integer
+end
+
+class Audio < CouchbaseOrm::Base
+  attribute :url, :string
+  attribute :bitrate, :integer
+end
+
+class Post < CouchbaseOrm::Base
+  embeds_one :media, polymorphic: true
+end
+
+class RestrictedPost < CouchbaseOrm::Base
+  embeds_one :media, polymorphic: ['Image', 'Video']
+end
+
 describe CouchbaseOrm::EmbedsOne do
   let(:raw_data) { { bio: 'Software Engineer' } }
 
@@ -377,4 +407,164 @@ class Article < CouchbaseOrm::Base
       article.destroy! if article&.persisted?
     end
   end
+
+  describe 'polymorphic embeds_one' do
+    it 'can embed different types polymorphically with type attribute' do
+      image = Image.new(url: 'https://example.com/image.jpg', caption: 'A beautiful sunset')
+      post = Post.new(media: image)
+
+      expect(post.media).to be_a(Image)
+      expect(post.media.url).to eq('https://example.com/image.jpg')
+      expect(post.media.caption).to eq('A beautiful sunset')
+      expect(post.attributes['media']['type']).to eq('Image')
+    end
+
+    it 'can embed a different polymorphic type' do
+      video = Video.new(url: 'https://example.com/video.mp4', duration: 120)
+      post = Post.new(media: video)
+
+      expect(post.media).to be_a(Video)
+      expect(post.media.url).to eq('https://example.com/video.mp4')
+      expect(post.media.duration).to eq(120)
+      expect(post.attributes['media']['type']).to eq('Video')
+    end
+
+    it 'persists and retrieves polymorphic embedded objects correctly' do
+      video = Video.new(url: 'https://example.com/demo.mp4', duration: 90)
+      post = Post.create!(media: video)
+
+      loaded = Post.find(post.id)
+      expect(loaded.media).to be_a(Video)
+      expect(loaded.media.url).to eq('https://example.com/demo.mp4')
+      expect(loaded.media.duration).to eq(90)
+    ensure
+      post.destroy! if post&.persisted?
+    end
+
+    it 'can switch between different polymorphic types' do
+      image = Image.new(url: 'https://example.com/pic.jpg', caption: 'Original')
+      post = Post.create!(media: image)
+
+      post.media = Video.new(url: 'https://example.com/clip.mp4', duration: 45)
+      post.save!
+
+      post.reload
+      expect(post.media).to be_a(Video)
+      expect(post.media.url).to eq('https://example.com/clip.mp4')
+    ensure
+      post.destroy! if post&.persisted?
+    end
+
+    it 'sets embedded flag on polymorphic embedded objects' do
+      image = Image.new(url: 'https://example.com/test.jpg', caption: 'Test')
+      post = Post.new(media: image)
+
+      expect(post.media.instance_variable_get(:@_embedded)).to be true
+    end
+
+    it 'can set polymorphic embedded to nil' do
+      video = Video.new(url: 'https://example.com/test.mp4', duration: 60)
+      post = Post.new(media: video)
+
+      post.media = nil
+      expect(post.media).to be_nil
+      expect(post.attributes['media']).to be_nil
+      expect(post.attributes['media_type']).to be_nil
+    end
+
+    it 'validates polymorphic embedded objects' do
+      # Assuming Image has validations
+      image = Image.new(url: nil, caption: 'No URL')
+      post = Post.new(media: image)
+
+      # Since Image doesn't have validations in our test setup, this would pass
+      # But demonstrates the structure for validation testing
+      expect(post.media).to be_a(Image)
+    end
+
+    it 'accepts hash with type key for polymorphic embeds_one' do
+      post = Post.new(media: { type: 'image', url: 'https://example.com/hash.jpg', caption: 'From Hash' })
+
+      expect(post.media).to be_a(Image)
+      expect(post.media.url).to eq('https://example.com/hash.jpg')
+      expect(post.media.caption).to eq('From Hash')
+      expect(post.attributes['media']['type']).to eq('Image')
+    end
+
+    it 'accepts hash with string type key for polymorphic embeds_one' do
+      post = Post.new(media: { 'type' => 'video', 'url' => 'https://example.com/hash.mp4', 'duration' => 75 })
+
+      expect(post.media).to be_a(Video)
+      expect(post.media.url).to eq('https://example.com/hash.mp4')
+      expect(post.media.duration).to eq(75)
+      expect(post.attributes['media']['type']).to eq('Video')
+    end
+
+    it 'raises error when hash is missing type key for polymorphic embeds_one' do
+      expect {
+        Post.new(media: { url: 'https://example.com/no-type.jpg', caption: 'Missing Type' })
+      }.to raise_error(ArgumentError, "Cannot infer type from Hash for polymorphic embeds_one. Include 'type' key with class name.")
+    end
+
+    it 'persists and retrieves polymorphic embedded from hash' do
+      post = Post.create!(media: { type: 'image', url: 'https://example.com/persist.jpg', caption: 'Persisted' })
+
+      loaded = Post.find(post.id)
+      expect(loaded.media).to be_a(Image)
+      expect(loaded.media.url).to eq('https://example.com/persist.jpg')
+      expect(loaded.media.caption).to eq('Persisted')
+    ensure
+      post.destroy! if post&.persisted?
+    end
+
+    it 'includes type in serialized attributes' do
+      post = Post.new(media: { type: 'video', url: 'https://example.com/test.mp4', duration: 100 })
+
+      serialized = post.send(:serialized_attributes)
+      expect(serialized['media']).to have_key('type')
+      expect(serialized['media']['type']).to eq('Video')
+    end
+  end
+
+  describe 'polymorphic embeds_one with types restriction' do
+    it 'accepts allowed types with objects' do
+      image = Image.new(url: 'https://example.com/allowed.jpg', caption: 'Allowed')
+      post = RestrictedPost.new(media: image)
+
+      expect(post.media).to be_a(Image)
+      expect(post.media.url).to eq('https://example.com/allowed.jpg')
+    end
+
+    it 'accepts allowed types with hashes' do
+      post = RestrictedPost.new(media: { type: 'video', url: 'https://example.com/allowed.mp4', duration: 60 })
+
+      expect(post.media).to be_a(Video)
+      expect(post.media.url).to eq('https://example.com/allowed.mp4')
+    end
+
+    it 'rejects disallowed types with objects' do
+      audio = Audio.new(url: 'https://example.com/denied.mp3', bitrate: 128)
+      post = RestrictedPost.new(media: audio)
+
+      expect(post).not_to be_valid
+      expect(post.errors[:media]).to include('Audio is not an allowed type. Allowed types: Image, Video')
+    end
+
+    it 'rejects disallowed types with hashes' do
+      post = RestrictedPost.new(media: { type: 'audio', url: 'https://example.com/denied.mp3', bitrate: 128 })
+
+      expect(post).not_to be_valid
+      expect(post.errors[:media]).to include('Audio is not an allowed type. Allowed types: Image, Video')
+    end
+
+    it 'persists and retrieves with type restrictions' do
+      post = RestrictedPost.create!(media: { type: 'image', url: 'https://example.com/restricted.jpg', caption: 'Restricted' })
+
+      loaded = RestrictedPost.find(post.id)
+      expect(loaded.media).to be_a(Image)
+      expect(loaded.media.url).to eq('https://example.com/restricted.jpg')
+    ensure
+      post.destroy! if post&.persisted?
+    end
+  end
 end