initial docs

Author: davidism

docs/check_delete.md

@@ -1,2 +1,57 @@
 List Query Filters
 ==================
+
+The `model_list` query field generated for each model supports building
+arbitrarily complex filters with the `filter` argument.
+
+The `filter` argument takes a list of lists of filter item structures. Each
+filter item in a list is combined with `AND`. Each list of filter items is
+combined with `OR`. As a shortcut, GraphQL will wrap a single item in the two
+lists implicitly.
+
+Each filter item has the following keys:
+
+-   `path`, a column name on the model being queried, or a dotted path that
+    can access columns through one or more relationships from the initial model.
+-   `op`, an operator name, which is dependant on the column's type. See the
+    next section for the default operators.
+-   `not`, an optional boolean to negate the filter. For example, the `eq` op
+    can be turned into `not eq` without needing to define a separate operator.
+-   `value`, the value to filter on. In simple cases, this will be a single
+    value, but some operators like `eq` support a list of values as a shortcut
+    to specifying multiple filter items. It can be arbitrary JSON data to
+    support anything custom operators might use.
+
+
+Operators
+---------
+
+Different filter operations are available depending on the type of the column.
+The {data}`.filters.type_ops` data structure maps SQLAlchemy types to operation
+names to functions that apply the operation.
+
+-   {class}`~sqlalchemy.types.String`
+    -   `eq`, exact equality. Accepts a single value or list.
+    -   `like`, case-insensitive partial match. Accepts a single value or list.
+        SQL wildcard characters are escaped.
+-   {class}`~sqlalchemy.types.Integer`, {class}`~sqlalchemy.types.Float`,
+    {class}`~sqlalchemy.types.DateTime`
+    -   `eq`, exact equality. Accepts a single value or list.
+    -   `lt`, less than a single value.
+    -   `le`, less than or equal to a single value.
+    -   `ge`, greater than or equal to a single value.
+    -   `gt`, greater than a single value.
+-   {class}`~sqlalchemy.types.Boolean`
+    -   `eq`, true or false.
+-   {class}`~sqlalchemy.types.DateTime`
+    -   `eq`, exact equality. Accepts a single value or list.
+
+
+Custom Operators
+----------------
+
+You can add operators for other types, or add to the operators for an existing
+type, by modifying the {data}`.filter.type_ops` structure. An operator function
+takes the SQLAlchemy column being filtered, and the list of values (will be a
+list even if a single value was given), and should return a SQLAlchemy
+expression that can be used with `WHERE`.

docs/filters.md

@@ -30,8 +30,8 @@ provides:
 
 start
 filters
-search
-check_delete
+q-search
+q-check_delete
 model
 api
 changes

docs/index.md

@@ -53,8 +53,31 @@ in {class}`magql.NonNull` appropriately for field and argument types.
 Relationships
 -------------
 
+For each relationship, a field will be generated on the object with the type of
+the related model's object. To-one relationships will be single objects, to-many
+relationships will be wrapped in {class}`magql.List`.
 
+Relationships are also available as arguments to the `model_create` and
+`model_update` mutation fields. In this case, they accept primary key value (or
+values), and validate that the referenced rows exists.
+
+When querying and selecting nested objects and fields across relationships,
+Magql-SQLAlchemy will generate efficient eager loads for the selected
+relationships. This means SQLAlchemy will emit a minimal number of queries to
+load all data. You can observe this by turing `echo=True` on for your
+SQLAlchemy engine.
 
 
 Validators
 ----------
+
+Two types of validators are automatically generated as needed:
+
+-   For each column marked `unique=True`, and for each `UniqueConstraint` that
+    applies to one or more columns, a validator will check that the values given
+    during create or update are unique. The validator can handle multiple
+    columns, defaults, and existing values for partial update. See
+    {class}`.UniqueValidator`.
+-   For each relationship, a validator will check that the given primary keys
+    exist, for to-one and to-many relationships. See
+    {class}`.ItemExistsValidator` and {class}`.ListExistsValidator`.

docs/model.md

@@ -0,0 +1,56 @@
+Preview Delete Effects Query
+============================
+
+Magql-SQLAlchemy provides a `check_delete` query field that can show the effects
+of deleting a row. This is done purely through introspection and does not
+perform an actual deletion. This can be used in a UI to show an "Are you sure
+you want to delete?" prompt with helpful information, or an explanation about
+why something can't be deleted.
+
+
+The Query and Results
+---------------------
+
+The field takes two arguments, `type` is the name of the model, and `id` is the
+primary key of the row. It returns three lists, with items in the same format
+as {doc}`q-search`.
+
+-   `affected`, model rows that would change somehow. A nullable to-one
+    relationship is cleared, or the row is removed from a to-many relationship.
+-   `deleted`, model rows that would be deleted along with the checked row. Rows
+    in a relationship that has `cascade='delete'` (or usually `all`) set.
+-   `prevented`, model rows that would cause the deletion to fail. A non-null
+    relationship.
+
+The items in each list have the following keys:
+
+-   `type`, the name of the model class.
+-   `id`, the primary key of the row.
+-   `value`, the string representation of the model row (`str(item)`).
+-   `extra`, currently unused, arbitrary extra information about the row.
+
+
+How It Works
+------------
+
+The query finds the SQLAlchemy model by name, then selects the row by id from
+the database. Then it examines all the relationship properties of the model to
+build the lists described above. Therefore, only data with SQLAlchemy
+`relationship` properties can be returned in the result.
+
+It's recommended that all relationships are two-way, with a property on each
+model and with `back_populates` set on both. If one side does not have a
+relationship, then checking its deletion cannot warn about affected rows or
+that the database will raise an error.
+
+
+Excluding Models
+----------------
+
+If you don't want to be able check a given model, you can remove it from the
+{class}`.CheckDelete.managers` map. However, it may still show up in the results
+of deleting other models if they have relationships to it.
+
+```python
+del model_group.check_delete.managers["UserSession"]
+```

docs/q-check_delete.md

@@ -0,0 +1,49 @@
+Global Search Query
+===================
+
+Magql provides a `search` query field that will perform a global search using
+registered providers. Magql-SQLAlchemy registers a provider for each model that
+will search all string columns.
+
+
+The Query and Results
+---------------------
+
+The `search` query field takes one argument, `value`, the string to search for.
+It returns a list of items.
+
+The items in the list have the following keys:
+
+-   `type`, the name of the model class.
+-   `id`, the primary key of the row.
+-   `value`, the string representation of the model row (`str(item)`).
+-   `extra`, currently unused, arbitrary extra information about the row.
+
+Using the `type` and `id`, a UI could present search results that link to that
+item.
+
+
+Disabling for a Model
+---------------------
+
+When using {class}`.ModelGroup.from_declarative_base`, it takes a `search`
+argument to control what models are searchable.
+
+By default, `search` is `True`, which generates a search provider for ever
+model. You can reassign {attr}`.ModelManager.search_provider` to `None` to
+disable search for that model. If you set `search` to `False`, no providers will
+be generated.
+
+You can pass a set of model classes and/or model names to `search` to
+generate providers only for those models.
+
+
+Customizing a Provider
+----------------------
+
+The default search provider for each model is {class}`.ColumnSearchProvider`,
+which generates a `ILIKE` query against all of the model's string-like columns.
+
+{attr}`.ModelManager.search_provider` can be reassigned to any callable that
+takes a `value` argument and returns a list of
+{class}`magql.search.SearchResult` instances.

docs/q-search.md

@@ -125,9 +125,9 @@ a model. Let's look at what it created for the `Task` model:
 It also provides two global queries:
 
 *   `search` takes a value and searches all string columns in all models. A UI
-    could use this to provide a global search bar. See {doc}`search`.
+    could use this to provide a global search bar. See {doc}`q-search`.
 *   `check_delete(type, id)` takes a model name and row id and checks what would
-    be affected if the row was deleted. See {doc}`check_delete`.
+    be affected if the row was deleted. See {doc}`q-check_delete`.
 
 
 Customizing the Schema