From 23ae65dd679a8748d4212cb9c7d47caadae47137 Mon Sep 17 00:00:00 2001
From: linrongbin16 <linrongbin16@outlook.com>
Date: Tue, 11 Jan 2022 14:31:24 +0800
Subject: [PATCH] add Dynamic-Insert.md (#413)

Add Dynamic-Insert.md
---
 docs/Dynamic-Insert.md | 33 +++++++++++++++++++++++++++++++++
 docs/Insert.md         |  7 +++++++
 2 files changed, 40 insertions(+)
 create mode 100644 docs/Dynamic-Insert.md

diff --git a/docs/Dynamic-Insert.md b/docs/Dynamic-Insert.md
new file mode 100644
index 00000000..905e1f10
--- /dev/null
+++ b/docs/Dynamic-Insert.md
@@ -0,0 +1,33 @@
+# Introduction
+_This page explains dynamic insert statements. Before studying this page, you should read about [static insert statements](Insert.md)._
+
+If you know the exact structure of your inserts at compile time, statically constructed insert statements are perfect. But if the structure depends on runtime information like user input, you will need dynamic insert statements. For those only provide part fields of table schema, leave others to default value or NULL, dynamic insert statement is a must. Depending on your needs, you can choose the required dosage.
+
+# A Basic Example
+So let us construct insert statement with a dynamic part
+```C++
+auto s = dynamic_insert_into(db, foo).dynamic_set(
+    foo.name = name,
+);
+s.insert_list.add(foo.id = runtimeStatement.id);
+s.insert_list.add(foo.hasFun = runtimeStatement.hasFun);
+const int64_t result = db(s);
+```
+Admittedly, a rather simplistic example (please suggest nicer ones), but anyway, this is what's happening:
+```C++
+dynamic_insert_into(db, table) 
+```
+This initializes a dynamic insert. One major difference between `dynamic_insert_into` and `insert_into` is the first argument of `dynamic_insert_into`: a database connection. This is used to evaluate the dynamic parts of the statement as they are added.
+
+```C++
+.dynamic_set(...);
+...
+s.insert_list.add(foo.id = runtimeStatement.id);
+s.insert_list.add(foo.hasFun = runtimeStatement.hasFun);
+```
+The first part creates a new insert object that accepts a dynamically constructed set expression. In this case the user can determine whether to search for a certain id or a certain hasFun, or neither or both.
+
+```C++
+const int64_t result = db(s);
+```
+Finally use `db(s)` to execute the insert statement, and returns a `int64_t` value. If `foo.id` column is a `AUTO INCREMENT` (auto generated) id field, this will returns the auto generated id, for others this will returns 0.
diff --git a/docs/Insert.md b/docs/Insert.md
index f1375046..e8656f07 100644
--- a/docs/Insert.md
+++ b/docs/Insert.md
@@ -1,3 +1,8 @@
+# Introduction
+_This page explains insert statements with a static structure. If you want to learn about constructing insert statements at runtime, you should still read this page first and then move on to [dynamic insert statements](Dynamic-Insert.md)._
+
+# A Basic example
+
 Haven't found the time to document this in any detail, yet, but this is an example:
 
 ```C++
@@ -33,3 +38,5 @@ time point.
 ```
 
 Similar for other data types.
+
+See also [dynamic insert statements](Dynamic-Insert.md).
\ No newline at end of file