core.bones.randomslice
======================

.. py:module:: core.bones.randomslice


Classes
-------

.. autoapisummary::

   core.bones.randomslice.RandomSliceBone


Module Contents
---------------

.. py:class:: RandomSliceBone(*, visible=False, readOnly=True, slices=2, sliceSize=0.5, **kwargs)

   Bases: :py:obj:`viur.core.bones.base.BaseBone`


   This class is particularly useful when you want to retrieve a random sample of elements from a
   larger dataset without needing to fetch all the data from the database. By performing multiple
   subqueries and processing the results, RandomSliceBone provides an efficient way to get a
   randomized selection of elements from the database query.
   Simulates the orderby=random from SQL.
   If you sort by this bone, the query will return a random set of elements from that query.

   :param visible: Indicates if the bone is visible, defaults to False.
   :param readOnly: Indicates if the bone is read-only, defaults to True.
   :param slices: The number of slices to use, defaults to 2.
   :param sliceSize: The size of each slice, defaults to 0.5.
   :param kwargs: Additional keyword arguments.

   Initializes a new RandomSliceBone.




   .. py:attribute:: type
      :value: 'randomslice'



   .. py:attribute:: slices
      :value: 2



   .. py:attribute:: sliceSize
      :value: 0.5



   .. py:method:: serialize(skel, name, parentIndexed)

      Serializes the bone into a format that can be written into the datastore. Instead of using
      the existing value, it writes a randomly chosen float in the range [0, 1) as the value for
      this bone.

      :param SkeletonInstance skel: The SkeletonInstance this bone is part of.
      :param str name: The property name this bone has in its Skeleton (not the description).
      :param bool parentIndexed: Indicates if the parent bone is indexed.
      :return: Returns True if the serialization is successful.
      :rtype: bool



   .. py:method:: buildDBSort(name, skel, dbFilter, rawFilter)

      Modifies the database query to return a random selection of elements by creating multiple
      subqueries, each covering a slice of the data. This method doesn't just change the order of
      the selected elements, but also changes which elements are returned.

      :param str name: The property name this bone has in its Skeleton (not the description).
      :param SkeletonInstance skel: The :class:viur.core.skeleton.Skeleton instance this bone is part of.
      :param db.Query dbFilter: The current :class:viur.core.db.Query instance the filters should be applied to.
      :param Dict rawFilter: The dictionary of filters the client wants to have applied.
      :return: The modified :class:viur.core.db.Query instance.
      :rtype: Optional[db.Query]

      .. note:: The rawFilter is controlled by the client, so you must expect and safely handle
          malformed data.

      The method also contains an inner function, applyFilterHook, that applies the filter hook to
      the given filter if set, or returns the unmodified filter. This allows the orderby=random
      functionality to be used in relational queries as well.



   .. py:method:: calculateInternalMultiQueryLimit(query, targetAmount)

      Calculates the number of entries to be fetched in each subquery.

      :param db.Query query: The :class:viur.core.db.Query instance.
      :param int targetAmount: The number of entries to be returned from the db.Query.
      :return: The number of elements the db.Query should fetch on each subquery.
      :rtype: int



   .. py:method:: customMultiQueryMerge(dbFilter, result, targetAmount)

      Merges the results of multiple subqueries by randomly selecting 'targetAmount' elements
      from the combined 'result' list.

      :param db.Query dbFilter: The db.Query instance calling this function.
      :param List[db.Entity] result: The list of results for each subquery that has been run.
      :param int targetAmount: The number of results to be returned from the db.Query.
      :return: A list of elements to be returned from the db.Query.
      :rtype: List[db.Entity]