Collection for SequoiaDB
All operation need deal with the error code returned first, if it has.
Every error code is not SDB_OK(or 0), it means something error has appeared,
and user should deal with it according the meaning of error code printed.
@version: execute to get version
>>> import pysequoiadb
>>> print pysequoiadb.get_version()
@notice : The dict of built-in Python is hashed and non-ordered. so the
element in dict may not the order we make it. we make a dict and
print it like this:
...
>>> a = {"avg_age":24, "major":"computer science"}
>>> a
>>> {'major': 'computer science', 'avg_age': 24}
...
the elements order it is not we make it!!
therefore, we use bson.SON to make the order-sensitive dict if the
order is important such as operations in "$sort", "$group",
"split_by_condition", "aggregate","create_collection"...
In every scene which the order is important, please make it using
bson.SON and list. It is a subclass of built-in dict
and order-sensitive
| def pysequoiadb.collection.collection.alter |
( |
|
self, |
|
|
|
options |
|
) |
| |
Alter the collection.
Parameters:
Name Type Info:
options dict The options are as following:
ReplSize : Assign how many replica nodes need to be synchronized when a write
request (insert, update, etc) is executed, default is 1
ShardingKey : Assign the sharding key, foramt: { ShardingKey: { <key name>: <1/-1>} },
1 indicates positive order, -1 indicates reverse order.
e.g. { ShardingKey: { age: 1 } }
ShardingType : Assign the sharding type, default is "hash"
Partition : The number of partition, it is valid when ShardingType is "hash",
the range is [2^3,2^20], default is 4096
AutoSplit : Whether to enable the automatic partitioning, it is valid when
ShardingType is "hash", defalut is false
EnsureShardingIndex : Whether to build sharding index, default is true
Compressed : Whether to enable data compression, default is true
CompressionType : The compression type of data, could be "snappy" or "lzw", default is "lzw"
StrictDataMode : Whether to enable strict date mode in numeric operations, default is false
AutoIncrement : Assign attributes of an autoincrement field or batch autoincrement fields
e.g. { AutoIncrement : { Field : "a", MaxValue : 2000 } },
{ AutoIncrement : [ { Field : "a", MaxValue : 2000}, { Field : "a", MaxValue : 4000 } ] }
AutoIndexId : Whether to build "$id" index, default is true
Exceptions:
pysequoiadb.error.SDBBaseError
| def pysequoiadb.collection.collection.bulk_insert |
( |
|
self, |
|
|
|
flag, |
|
|
|
records |
|
) |
| |
Insert a bulk of record into current collection.
Parameters:
Name Type Info:
flag int See Info as below.
records list/tuple The list of inserted records.
Return values:
A dict object contains the insert details. As follow:
- InsertedNum : The number of records successfully inserted, including replaced and ignored records.
- DuplicatedNum : The number of records ignored or replaced due to duplicate key conflicts.
- LastGenerateID : The max value of all auto-increments that the first record inserted contains. The
result will include this field if current collection has auto-increments.
- _id : ObjectId of the inserted record. The result will include field "_id" if
FLG_INSERT_RETURN_OID is used.
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
The flag to control the behavior of inserting. The value of flag default to be INSERT_FLG_DEFAULT, and it
can choose the follow values:
INSERT_FLG_DEFAULT : While INSERT_FLG_DEFAULT is set, database will stop inserting when the record
hit index key duplicate error.
INSERT_FLG_CONTONDUP : If the record hit index key duplicate error, database will skip it.
INSERT_FLG_RETURN_OID : Return the value of "_id" field in the record.
INSERT_FLG_REPLACEONDUP : If the record hit index key duplicate error, database will replace the existing
record by the inserting new record and then go on inserting.
INSERT_FLG_CONTONDUP_ID : The flag represent the error of the dup key will be ignored when the dup key is '_id'.
INSERT_FLG_REPLACEONDUP_ID : The flag represents the error of the dup key will be ignored when the dup key is '_id',
and the original record will be replaced by new record.
| def pysequoiadb.collection.collection.explain |
( |
|
self, |
|
|
|
kwargs |
|
) |
| |
Get the matching documents in current collection.
Parameters:
Name Type Info:
**kwargs Useful options are below
- condition dict The matching rule, update all the
documents if not provided.
- selected dict The selective rule, return the whole
document if not provided.
- order_by dict The ordered rule, result set is unordered
if not provided.
- hint dict The hint, automatically match the optimal
hint if not provided.
- num_to_skip long Skip the first numToSkip documents,
default is 0L.
- num_to_return long Only return numToReturn documents,
default is -1L for returning
all results.
- flags int The query flags, default to be 0. Please see
the definition of follow flags for
more detail. See Info as below.
- options dict
Return values:
a cursor object of query
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
query flags:
QUERY_FLG_FORCE_HINT : Force to use specified hint to query, if database has no index assigned by the hint, fail to query
QUERY_FLG_PARALLED : Enable parallel sub-query, each sub-query will finish scanning different part of data
QUERY_FLG_WITH_RETURNDATA : In general, query won't return data until cursor gets the record from database, when adding this flag, return data in query response, it will be more high-performance
| def pysequoiadb.collection.collection.get_query_meta |
( |
|
self, |
|
|
|
kwargs |
|
) |
| |
Get the index blocks' or data blocks' infomations for concurrent query.
Parameters:
Name Type Info:
**kwargs Useful options are below
- condition dict The matching rule, return the whole range
of index blocks if not provided.
eg:{"age":{"$gt":25},"age":{"$lt":75}}.
- order_by dict The ordered rule, result set is unordered
if not provided.bson.SON may need if it is
order-sensitive.
- hint dict One of the indexs in current collection,
using default index to query if not
provided.
eg:{"":"ageIndex"}.
- num_to_skip long Skip the first num_to_skip documents,
default is 0L.
- num_to_return long Only return num_to_return documents,
default is -1L for returning all results.
Return values:
a cursor object of query
Exceptions:
pysequoiadb.error.SDBBaseError
| def pysequoiadb.collection.collection.insert_with_flag |
( |
|
self, |
|
|
|
record, |
|
|
|
flag = INSERT_FLG_DEFAULT |
|
) |
| |
Insert a record into current collection.
Parameters:
Name Type Info:
record dict The inserted record.
flag int See Info as below.
Return values:
A dict object contains the insert details. As follow:
- InsertedNum : The number of records successfully inserted, including replaced and ignored records.
- DuplicatedNum : The number of records ignored or replaced due to duplicate key conflicts.
- LastGenerateID : The max value of all auto-increments that the inserted record contains. The result
will include this field if current collection has auto-increments.
- _id : ObjectId of the inserted record. The result will include field "_id" if
FLG_INSERT_RETURN_OID is used.
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
The flag to control the behavior of inserting. The value of flag default to be INSERT_FLG_DEFAULT, and it
can choose the follow values:
INSERT_FLG_DEFAULT : While INSERT_FLG_DEFAULT is set, database will stop inserting when the record
hit index key duplicate error.
INSERT_FLG_CONTONDUP : If the record hit index key duplicate error, database will skip it.
INSERT_FLG_RETURN_OID : Return the value of "_id" field in the record.
INSERT_FLG_REPLACEONDUP : If the record hit index key duplicate error, database will replace the existing
record by the inserting new record and then go on inserting.
INSERT_FLG_CONTONDUP_ID : The flag represent the error of the dup key will be ignored when the dup key is '_id'.
INSERT_FLG_REPLACEONDUP_ID : The flag represents the error of the dup key will be ignored when the dup key is '_id',
and the original record will be replaced by new record.
| def pysequoiadb.collection.collection.list_lobs |
( |
|
self, |
|
|
|
kwargs |
|
) |
| |
list lobs.
Parameters:
Name Type Info:
- condition dict The matching rule, return all the lob if not provided.
- selected dict The selective rule, return the whole infomation if not provided.
- order_by dict The ordered rule, result set is unordered if not provided.
- hint dict Specified options. eg. {"ListPieces": 1} means get the detail piece info of lobs.
- num_to_skip long Skip the first numToSkip lob, default is 0.
- num_to_Return long Only return numToReturn lob, default is -1 for returning all results.
Return values:
a cursor object of query
Exceptions:
pysequoiadb.error.SDBBaseError
| def pysequoiadb.collection.collection.query |
( |
|
self, |
|
|
|
kwargs |
|
) |
| |
Get the matching documents in current collection.
Parameters:
Name Type Info:
**kwargs Useful options are below
- condition dict The matching rule, update all the
documents if not provided.
- selector dict The selective rule, return the whole
document if not provided.
- order_by dict The ordered rule, result set is unordered
if not provided.
- hint dict The hint, automatically match the optimal
hint if not provided.
- num_to_skip long Skip the first numToSkip documents,
default is 0L.
- num_to_return long Only return numToReturn documents,
default is -1L for returning
all results.
- flags int The query flags, default to be 0. Please see
the definition of follow flags for
more detail. See Info as below.
Return values:
a cursor object of query
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
query flags:
QUERY_FLG_FORCE_HINT : Force to use specified hint to query, if database has no index assigned by the hint, fail to query
QUERY_FLG_PARALLED : Enable parallel sub-query, each sub-query will finish scanning different part of data
QUERY_FLG_WITH_RETURNDATA : In general, query won't return data until cursor gets the record from database, when adding this flag, return data in query response, it will be more high-performance
QUERY_PREPARE_MORE : Enable prepare more data when querying
QUERY_FLG_FOR_UPDATE : When the transaction is turned on and the transaction isolation level is "RC", the transaction lock will be released after the record is read by default.
However, when setting this flag, the transaction lock will not be released until the transaction is committed or rollbacked. When the transaction is turned off or
the transaction isolation level is "RU", the flag does not work
| def pysequoiadb.collection.collection.query_and_remove |
( |
|
self, |
|
|
|
kwargs |
|
) |
| |
Get the matching documents in current collection and remove.
Parameters:
Name Type Info:
**kwargs Useful options are below
- condition dict The matching rule, update all the
documents if not provided.
- selector dict The selective rule, return the whole
document if not provided.
- order_by dict The ordered rule, result set is unordered
if not provided.
- hint dict The hint, automatically match the optimal
hint if not provided.
- num_to_skip long Skip the first numToSkip documents,
default is 0L.
- num_to_return long Only return numToReturn documents,
default is -1L for returning
all results.
- flags int The query flags, default to be 0. Please see
the definition of follow flags for
more detail. See Info as below.
Return values:
a cursor object of query
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
query flags:
QUERY_FLG_FORCE_HINT : Force to use specified hint to query, if database has no index assigned by the hint, fail to query
QUERY_FLG_PARALLED : Enable parallel sub-query, each sub-query will finish scanning different part of data
QUERY_FLG_WITH_RETURNDATA : In general, query won't return data until cursor gets the record from database, when adding this flag, return data in query response, it will be more high-performance
QUERY_FLG_FOR_UPDATE : When the transaction is turned on and the transaction isolation level is "RC", the transaction lock will be released after the record is read by default.
However, when setting this flag, the transaction lock will not be released until the transaction is committed or rollbacked. When the transaction is turned off or
the transaction isolation level is "RU", the flag does not work.
| def pysequoiadb.collection.collection.query_and_update |
( |
|
self, |
|
|
|
update, |
|
|
|
kwargs |
|
) |
| |
Get the matching documents in current collection and update.
Parameters:
Name Type Info:
update dict The update rule, can't be None.
**kwargs Useful options are below
- condition dict The matching rule, update all the
documents if not provided.
- selector dict The selective rule, return the whole
document if not provided.
- order_by dict The ordered rule, result set is unordered
if not provided.
- hint dict The hint, automatically match the optimal
hint if not provided.
- num_to_skip long Skip the first numToSkip documents,
default is 0L.
- num_to_return long Only return numToReturn documents,
default is -1L for returning
all results.
- flags int The query flags, default to be 0. Please see
the definition of follow flags for
more detail. See Info as below.
- return_new bool When True, returns the updated document rather than the original
Return values:
a cursor object of query
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
query flags:
QUERY_FLG_FORCE_HINT : Force to use specified hint to query, if database have
no index assigned by the hint, failed to query
QUERY_FLG_PARALLED : Enable parallel sub-query, each sub-query will finish scanning
different part of data
QUERY_FLG_WITH_RETURNDATA : In general, query won't return data until cursor gets from
database, when adding this flag, return data in query response,
it will be more high-performance
QUERY_FLG_KEEP_SHARDINGKEY_IN_UPDATE : The sharding key in update rule is not filtered, when executing
queryAndUpdate.
QUERY_FLG_FOR_UPDATE : When the transaction is turned on and the transaction isolation level is "RC", the transaction lock will be released after the record is read by default.
However, when setting this flag, the transaction lock will not be released until the transaction is committed or rollbacked. When the transaction is turned off or
the transaction isolation level is "RU", the flag does not work.
| def pysequoiadb.collection.collection.query_one |
( |
|
self, |
|
|
|
kwargs |
|
) |
| |
Get one matching documents in current collection.
Parameters:
Name Type Info:
**kwargs Useful options are below
- condition dict The matching rule, update all the
documents if not provided.
- selected dict The selective rule, return the whole
document if not provided.
- order_by dict The ordered rule, result set is unordered
if not provided.
- hint dict The hint, automatically match the optimal
hint if not provided.
- num_to_skip long Skip the first numToSkip documents,
default is 0L.
- flags int The query flags, default to be 0. Please see
the definition of follow flags for
more detail. See Info as below.
Return values:
a record of json/dict
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
query flags:
QUERY_FLG_FORCE_HINT : Force to use specified hint to query, if database has no index assigned by the hint, fail to query
QUERY_FLG_PARALLED : Enable parallel sub-query, each sub-query will finish scanning different part of data
QUERY_FLG_WITH_RETURNDATA : In general, query won't return data until cursor gets the record from database, when adding this flag, return data in query response, it will be more high-performance
QUERY_PREPARE_MORE : Enable prepare more data when querying
QUERY_FLG_FOR_UPDATE : When the transaction is turned on and the transaction isolation level is "RC", the transaction lock will be released after the record is read by default.
However, when setting this flag, the transaction lock will not be released until the transaction is committed or rollbacked. When the transaction is turned off or
the transaction isolation level is "RU", the flag does not work
| def pysequoiadb.collection.collection.set_attributes |
( |
|
self, |
|
|
|
options |
|
) |
| |
Alter the collection.
Parameters:
Name Type Info:
options dict The options to alter
ReplSize : Assign how many replica nodes need to be synchronized when a write request(insert, update, etc) is executed
ShardingKey : Assign the sharding key
ShardingType : Assign the sharding type
Partition : When the ShardingType is "hash", need to assign Partition, it's the bucket number for hash, the range is [2^3,2^20]
CompressionType : The compression type of data, could be "snappy" or "lzw"
EnsureShardingIndex : Assign to true to build sharding index
StrictDataMode : Using strict date mode in numeric operations or not
AutoIncrement : Assign attributes of an autoincrement field or batch autoincrement fields. e.g { "AutoIncrement": { "Field": "studentID", "StartValue": 1 } }
Exceptions:
pysequoiadb.error.SDBBaseError
| def pysequoiadb.collection.collection.split_async_by_condition |
( |
|
self, |
|
|
|
source_group_name, |
|
|
|
target_group_name, |
|
|
|
split_condition, |
|
|
|
split_end_condition = None |
|
) |
| |
Split the specified collection from source replica group to target
replica group by range.
Parameters:
Name Type Info:
source_group_name str The source replica group name.
target_group_name str The target replica group name.
split_condition dict The matching rule, return the count of
all documents if None.
split_end_condition dict The split end condition or None.
eg:
If we create a collection with the
option { ShardingKey:{"age":1},
ShardingType:"Hash",Partition:2^10 },
we can fill {age:30} as the
splitCondition, and fill {age:60}
as the splitEndCondition. when split,
the target replica group will get the
records whose age's hash value are in
[30,60). If splitEndCondition is null,
they are in [30,max).
Return values:
task id
Exceptions:
pysequoiadb.error.SDBBaseError
| def pysequoiadb.collection.collection.split_by_condition |
( |
|
self, |
|
|
|
source_group_name, |
|
|
|
target_group_name, |
|
|
|
split_condition, |
|
|
|
split_end_condition = None |
|
) |
| |
Split the specified collection from source replica group to target
replica group by range.
Parameters:
Name Type Info:
source_group_name str The source replica group name.
target_group_name str The target replica group name.
split_condition dict The matching rule, return the count
of all documents if None.
split_end_condition dict The split end condition or None.
eg:
If we create a collection with the
option { ShardingKey:{"age":1},
ShardingType:"Hash",Partition:2^10 },
we can fill {age:30} as the
splitCondition, and fill {age:60}
as the splitEndCondition. when
split, the target replica group
will get the records whose age's
hash value are in [30,60).
If splitEndCondition is null, they
are in [30,max).
Exceptions:
pysequoiadb.error.SDBBaseError
| def pysequoiadb.collection.collection.update |
( |
|
self, |
|
|
|
rule, |
|
|
|
kwargs |
|
) |
| |
Update the matching documents in current collection.
Parameters:
Name Type Info:
rule dict The updating rule.
**kwargs Useful option are below
- condition dict The matching rule, match all the documents
if not provided.
- hint dict The hint, automatically match the optimal hint
if not provided.
- flags int See Info as below.
Return values:
A dict object contains the update details. As follow:
- UpdatedNum : The number of records successfully updated, including records that match but have no
data changes.
- ModifiedNum : The number of records successfully updated with data changes.
- InsertedNum : The number of records successfully inserted.
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
The update flags, default to be 0, it can choose the follow values:
UPDATE_FLG_KEEP_SHARDINGKEY : The sharding key in update rule is not filtered, when executing
update or upsert.
UPDATE_FLG_UPDATE_ONE : The flag represent whether to update only one matched record or all
matched records.
Note:
When flag is set to 0, it won't work to update the "ShardingKey" field, but the
other fields take effect.
| def pysequoiadb.collection.collection.upsert |
( |
|
self, |
|
|
|
rule, |
|
|
|
kwargs |
|
) |
| |
Update the matching documents in current collection, insert if
no matching.
Parameters:
Name Type Info:
rule dict The updating rule.
**kwargs Useful options are below
- condition dict The matching rule, match all the documents
if not provided.
- hint dict The hint, automatically match the optimal hint
if not provided.
- setOnInsert dict The setOnInsert assigns the specified values
to the fields when insert.
- flags int See Info as below.
Return values:
A dict object contains the upsert details. As follow:
- UpdatedNum : The number of records successfully updated, including records that match but have no
data changes.
- ModifiedNum : The number of records successfully updated with data changes.
- InsertedNum : The number of records successfully inserted.
Exceptions:
pysequoiadb.error.SDBBaseError
Info:
The update flags, default to be 0, it can choose the follow values:
UPDATE_FLG_KEEP_SHARDINGKEY : The sharding key in update rule is not filtered, when executing
update or upsert.
UPDATE_FLG_UPDATE_ONE : The flag represent whether to update only one matched record or all
matched records.
Note:
When flag is set to 0, it won't work to update the "ShardingKey" field, but the
other fields take effect.
1.8.2