1.1
1.2
1.3
1.4
1.4.1
1.4.2
1.4.3
1.5
1.5.1
1.5.2
1.5.3
1.6
1.6.1
1.6.2
1.7
1.7.1
1.7.2
1.8
1.8.1
1.8.2
1.8.3
1.9
1.10
1.10.1
1.10.2
1.11
1.12
1.13
1.14
1.15
1.16
1.16.1
1.16.2
1.16.3
1.16.4
1.17
1.17.1
1.17.2
1.17.3
1.17.4
1.17.5
TableofContentsIntroduction
GeneralHTTPHandling
HTTPInterface
Databases
To-Endpoint
Management
NotesonDatabases
Collections
Creating
GettingInformation
Modifying
Documents
BasicsandTerminology
WorkingwithDocuments
Edges
AddressandEtag
WorkingwithEdges
GeneralGraph
Management
Vertices
Edges
Traversals
AQLQueryCursors
QueryResults
AccessingCursors
AQLQueries
AQLQueryCache
AQLUserFunctionsManagement
SimpleQueries
AsyncResultHandling
BulkImport/Export
JSONDocuments
Headers&Values
BatchRequests
Exportingdata
Indexes
WorkingwithIndexes
Hash
Skiplist
Persistent
Geo
1
1.17.6
1.18
1.19
1.19.1
1.19.2
1.19.3
1.19.4
1.20
1.21
1.22
1.23
1.23.1
1.23.2
1.23.3
1.24
1.25
1.26
1.27
Fulltext
Transactions
Replication
ReplicationDump
ReplicationLogger
ReplicationApplier
OtherReplicationCommands
Sharding
Monitoring
Endpoints
FoxxServices
Management
Configuration
Miscellaneous
UserManagement
Tasks
Agency
Miscellaneousfunctions
2
ArangoDBv3.3.3HTTPAPIDocumentationWelcometotheArangoDBHTTPAPIdocumentation!ThisdocumentationisforAPIdevelopers.AsauseroradministratorofArangoDByoushouldnotneedtheinformationprovidedherein.
Ingeneral,asauserofArangoDByouwilluseoneofthelanguagedrivers.
Introduction
3
GeneralHTTPRequestHandlinginArangoDB
Protocol
ArangoDBexposesitsAPIviaHTTP,makingtheserveraccessibleeasilywithavarietyofclientsandtools(e.g.browsers,curl,telnet).ThecommunicationcanoptionallybeSSL-encrypted.
ArangoDBusesthestandardHTTPmethods(e.g.GET,POST,PUT,DELETE)plusthePATCHmethoddescribedinRFC5789.
MostserverAPIsexpectclientstosendanypayloaddatainJSONformat.DetailsontheexpectedformatandJSONattributescanbefoundinthedocumentationoftheindividualservermethods.
ClientssendingrequeststoArangoDBmustuseeitherHTTP1.0orHTTP1.1.OtherHTTPversionsarenotsupportedbyArangoDBandanyattempttosendadifferentHTTPversionsignaturewillresultintheserverrespondingwithanHTTP505(HTTPversionnotsupported)error.
ArangoDBwillalwaysrespondtoclientrequestswithHTTP1.1.ClientsshouldthereforesupportHTTPversion1.1.
ClientsarerequiredtoincludetheContent-LengthHTTPheaderwiththecorrectcontentlengthineveryrequestthatcanhaveabody(e.g.POST,PUTorPATCH)request.ArangoDBwillnotprocessrequestswithoutaContent-Lengthheader-thuschunkedtransferencodingforPOST-documentsisnotsupported.
HTTPKeep-Alive
ArangoDBsupportsHTTPkeep-alive.IftheclientdoesnotsendaConnectionheaderinitsrequest,andtheclientusesHTTPversion1.1,ArangoDBwillassumetheclientwantstokeepalivetheconnection.Ifclientsdonotwishtousethekeep-alivefeature,theyshouldexplicitlyindicatethatbysendingaConnection:CloseHTTPheaderintherequest.
ArangoDBwillcloseconnectionsautomaticallyforclientsthatsendrequestsusingHTTP1.0,exceptiftheysendanConnection:Keep-Aliveheader.
ThedefaultKeep-Alivetimeoutcanbespecifiedatserverstartusingthe--http.keep-alive-timeoutparameter.
EstablishingTCPconnectionsisexpensive,sinceittakesseveralpingpongsbetweenthecommunicationparties.ThereforeyoucanuseconnectionkeepalivetosendseveralHTTPrequestoveroneTCP-connection;Eachrequestistreatedindependentlybydefinition.Youcanusethisfeaturetobuildupasocalledconnectionpoolwithseveralestablishedconnectionsinyourclientapplication,anddynamicallyre-useoneofthosethenidleconnectionsforsubsequentrequests.
Blockingvs.Non-blockingHTTPRequests
ArangoDBsupportsbothblockingandnon-blockingHTTPrequests.
ArangoDBisamulti-threadedserver,allowingtheprocessingofmultipleclientrequestsatthesametime.Request/responsehandlingandtheactualworkareperformedontheserverinparallelbymultipleworkerthreads.
Still,clientsneedtowaitfortheirrequeststobeprocessedbytheserver,andthuskeeponeconnectionofapooloccupied.Bydefault,theserverwillfullyprocessanincomingrequestandthenreturntheresulttotheclientwhentheoperationisfinished.Theclientmustwaitfortheserver'sHTTPresponsebeforeitcansendadditionalrequestsoverthesameconnection.Forclientsthataresingle-threadedand/orareblockingonI/Othemselves,waitingidlefortheserverresponsemaybenon-optimal.
Toreduceblockingontheclientside,ArangoDBoffersagenericmechanismfornon-blocking,asynchronousexecution:clientscanaddtheHTTPheaderx-arango-async:truetoanyoftheirrequests,markingthemastobeexecutedasynchronouslyontheserver.ArangoDBwillputsuchrequestsintoanin-memorytaskqueueandreturnanHTTP202(accepted)responsetotheclientinstantlyandthusfinishthisHTTP-request.Theserverwillexecutethetasksfromthequeueasynchronouslyasfastaspossible,whileclientscancontinuetodootherwork.Iftheserverqueueisfull(i.e.containsasmanytasksasspecifiedbytheoption"--scheduler.maximal-queue-size"),thentherequestwillberejectedinstantlywithanHTTP500(internalservererror)response.
GeneralHTTPHandling
4
Asynchronousexecutiondecouplestherequest/responsehandlingfromtheactualworktobeperformed,allowingfastserverresponsesandgreatlyreducingwaittimeforclients.Overallthisallowsformuchhigherthroughputthanifclientswouldalwayswaitfortheserver'sresponse.
Keepinmindthattheasynchronousexecutionisjust"fireandforget".ClientswillgetanyoftheirasynchronousrequestsansweredwithagenericHTTP202response.Atthetimetheserversendsthisresponse,itdoesnotknowwhethertherequestedoperationcanbecarriedoutsuccessfully(theactualoperationexecutionwillhappenatsomelaterpoint).Clientsthereforecannotmakeadecisionbasedontheserverresponseandmustrelyontheirrequestsbeingvalidandprocessablebytheserver.
Additionally,theserver'sasynchronoustaskqueueisanin-memorydatastructure,meaningnot-yetprocessedtasksfromthequeuemightbelostincaseofacrash.Clientsshouldthereforenotusetheasynchronousfeaturewhentheyhavestrictdurabilityrequirementsoriftheyrelyontheimmediateresultoftherequesttheysend.
FordetailsonthesubsequentprocessingreadonunderAsyncResulthandling.
Authentication
ClientauthenticationcanbeachievedbyusingtheAuthorizationHTTPheaderinclientrequests.ArangoDBsupportsauthenticationviaHTTPBasicorJWT.
AuthenticationisturnedonbydefaultforallinternaldatabaseAPIsbutturnedoffforcustomFoxxapps.TotoggleauthenticationforincomingrequeststotheinternaldatabaseAPIs,usetheoption--server.authentication.ThisoptionisturnedonbydefaultsoauthenticationisrequiredforthedatabaseAPIs.
PleasenotethatrequestsusingtheHTTPOPTIONSmethodwillbeansweredbyArangoDBinanycase,evenifnoauthenticationdataissentbytheclientoriftheauthenticationdataiswrong.ThisisrequiredforhandlingCORSpreflightrequests(seeCrossOriginResourceSharingrequests).TheresponsetoanHTTPOPTIONSrequestwillbegenericandnotexposeanyprivatedata.
ThereisanadditionaloptiontocontrolauthenticationforcustomFoxxapps.Theoption--server.authentication-system-onlycontrolswhetherauthenticationisrequiredonlyforrequeststotheinternaldatabaseAPIsandtheadmininterface.Itisturnedonbydefault,meaningthatotherAPIs(thisincludescustomFoxxapps)donotrequireauthentication.
ThedefaultvaluesallowexposingapubliccustomFoxxAPIbuiltwithArangoDBtotheoutsideworldwithouttheneedforHTTPauthentication,butstillprotectingtheusageoftheinternaldatabaseAPIs(i.e./_api/,/_admin/)withHTTPauthentication.
Iftheserverisstartedwiththe--server.authentication-system-onlyoptionsettofalse,allincomingrequestswillneedHTTPauthenticationiftheserverisconfiguredtorequireHTTPauthentication(i.e.--server.authenticationtrue).SettingtheoptiontotruewillmaketheserverrequireauthenticationonlyforrequeststotheinternaldatabaseAPIsandwillallowunauthenticatedrequeststoallotherURLs.
Here'sashortsummary:
--server.authenticationtrue--server.authentication-system-onlytrue:thiswillrequireauthenticationforallrequeststotheinternaldatabaseAPIsbutnotcustomFoxxapps.Thisisthedefaultsetting.--server.authenticationtrue--server.authentication-system-onlyfalse:thiswillrequireauthenticationforallrequests(includingcustomFoxxapps).--server.authenticationfalse:authenticationdisabledforallrequests
Wheneverauthenticationisrequiredandtheclienthasnotyetauthenticated,ArangoDBwillreturnHTTP401(Unauthorized).ItwillalsosendtheWWW-Authenticateresponseheader,indicatingthattheclientshouldprompttheuserforusernameandpasswordifsupported.Iftheclientisabrowser,thensendingbackthisheaderwillnormallytriggerthedisplayofthebrowser-sideHTTPauthenticationdialog.AsshowingthebrowserHTTPauthenticationdialogisundesiredinAJAXrequests,ArangoDBcanbetoldtonotsendtheWWW-Authenticateheaderbacktotheclient.WheneveraclientsendstheX-Omit-WWW-AuthenticateHTTPheader(withanarbitraryvalue)toArangoDB,ArangoDBwillonlysendstatuscode401,butnoWWW-Authenticateheader.Thisallowsclientstoimplementcredentialshandlingandbypassingthebrowser'sbuilt-indialog.
AuthenticationviaJWT
ToauthenticateviaJWTyoumustfirstobtainaJWT.TodososendaPOSTrequestto
/_open/auth
GeneralHTTPHandling
5
containingusernameandpasswordJSON-encodedlikeso:
{"username":"root","password":"rootPassword"}
Uponsuccesstheendpointwillreturna200OKandananswercontainingtheJWTinaJSON-encodedobjectlikeso:
{"jwt":"eyJhbGciOiJIUzI1NiI..x6EfI"}
ThisJWTshouldthenbeusedwithintheAuthorizationHTTPheaderinsubsequentrequests:
Authorization:bearereyJhbGciOiJIUzI1NiI..x6EfI
PleasenotethattheJWTwillexpireafter1monthandneedstobeupdated.
ArangoDBusesastandardJWTauthentication.Thesecretmayeitherbesetusing--server.jwt-secretorwillberandomlygenerateduponserverstartup.
FormoreinformationonJWTpleaseconsultRFC7519andhttps://jwt.io
ErrorHandling
ThefollowingshouldbenotedabouthowArangoDBhandlesclienterrorsinitsHTTPlayer:
clientrequestsusinganHTTPversionsignaturedifferentthanHTTP/1.0orHTTP/1.1willgetanHTTP505(HTTPversionnotsupported)errorinreturn.ArangoDBwillrejectclientrequestswithanegativevalueintheContent-LengthrequestheaderwithHTTP411(LengthRequired).Arangodbdoesn'tsupportPOSTwithtransfer-encoding:chunkedwhichforbidstheContent-Lengthheaderabove.themaximumURLlengthacceptedbyArangoDBis16K.IncomingrequestswithlongerURLswillberejectedwithanHTTP414(Request-URItoolong)error.iftheclientsendsaContent-Lengthheaderwithavaluebiggerthan0foranHTTPGET,HEAD,orDELETErequest,ArangoDBwillprocesstherequest,butwillwriteawarningtoitslogfile.whentheclientsendsaContent-Lengthheaderthathasavaluethatislowerthantheactualsizeofthebodysent,ArangoDBwillrespondwithHTTP400(BadRequest).ifclientssendaContent-Lengthvaluebiggerthantheactualsizeofthebodyoftherequest,ArangoDBwillwaitforabout90secondsfortheclienttocompleteitsrequest.Iftheclientdoesnotsendtheremainingbodydatawithinthistime,ArangoDBwillclosetheconnection.Clientsshouldavoidsendingsuchmalformedrequestsasthiswillblockonetcpconnection,andmayleadtoatemporaryfiledescriptorleak.whenclientssendabodyoraContent-Lengthvaluebiggerthanthemaximumallowedvalue(512MB),ArangoDBwillrespondwithHTTP413(RequestEntityTooLarge).iftheoveralllengthoftheHTTPheadersaclientsendsforonerequestexceedsthemaximumallowedsize(1MB),theserverwillfailwithHTTP431(RequestHeaderFieldsTooLarge).ifclientsrequestanHTTPmethodthatisnotsupportedbytheserver,ArangoDBwillreturnwithHTTP405(MethodNotAllowed).ArangoDBoffersgeneralsupportforthefollowingHTTPmethods:
GETPOSTPUTDELETEHEADPATCHOPTIONS
PleasenotethatnotallserveractionsallowusingalloftheseHTTPmethods.Youshouldlookupupthesupportedmethodsforeachmethodyouintendtouseinthemanual.
RequestsusinganyotherHTTPmethod(suchasforexampleCONNECT,TRACEetc.)willberejectedbyArangoDBasmentionedbefore.
Cross-OriginResourceSharing(CORS)requests
GeneralHTTPHandling
6
ArangoDBwillautomaticallyhandleCORSrequestsasfollows:
Preflight
Whenabrowseristoldtomakeacross-originrequestthatincludesexplicitheaders,credentialsorusesHTTPmethodsotherthanGETorPOST,itwillfirstperformaso-calledpreflightrequestusingtheOPTIONSmethod.
ArangoDBwillrespondtoOPTIONSrequestswithanHTTP200statusresponsewithanemptybody.Sincepreflightrequestsarenotexpectedtoincludeorevenindicatethepresenceofauthenticationcredentialsevenwhentheywillbepresentintheactualrequest,ArangoDBdoesnotenforceauthenticationforOPTIONSrequestsevenwhenauthenticationisenabled.
ArangoDBwillsetthefollowingheadersintheresponse:
access-control-allow-credentials:willbesettofalsebydefault.Fordetailsonwhenitwillbesettotrueseethenextsectiononcookies.
access-control-allow-headers:willbesettotheexectvalueoftherequest'saccess-control-request-headersheaderoromittedifnosuchheaderwassentintherequest.
access-control-allow-methods:willbesettoalistofallsupportedHTTPheadersregardlessofthetargetendpoint.Inotherwordsthatamethodislistedinthisheaderdoesnotguaranteethatitwillbesupportedbytheendpointintheactualrequest.
access-control-allow-origin:willbesettotheexactvalueoftherequest'soriginheader.
access-control-expose-headers:willbesettoalistofresponseheadersusedbytheArangoDBHTTPAPI.
access-control-max-age:willbesettoanimplementation-specifcvalue.
Actualrequest
IfarequestusinganyotherHTTPmethodthanOPTIONSincludesanoriginheader,ArangoDBwilladdthefollowingheaderstotheresponse:
access-control-allow-credentials:willbesettofalsebydefault.Fordetailsonwhenitwillbesettotrueseethenextsectiononcookies.
access-control-allow-origin:willbesettotheexactvalueoftherequest'soriginheader.
access-control-expose-headers:willbesettoalistofresponseheadersusedbytheArangoDBHTTPAPI.
WhenmakingCORSrequeststoendpointsofFoxxservices,thevalueoftheaccess-control-expose-headersheaderwillinsteadbesettoalistofresponseheadersusedintheresponseitself(butnotincludingtheaccess-control-headers).NotethatFoxxservicesmayoverridethisbehaviour.
Cookiesandauthentication
Inorderfortheclienttobeallowedtocorrectlyprovideauthenticationcredentialsorhandlecookies,ArangoDBneedstosettheaccess-control-allow-credentialsresponseheadertotrueinsteadoffalse.
ArangoDBwillautomaticallysetthisheadertotrueifthevalueoftherequest'soriginheadermatchesatrustedorigininthehttp.trusted-originconfigurationoption.TomakeArangoDBtrustacertainorigin,youcanprovideastartupoptionwhenrunningarangodlikethis:
--http.trusted-origin"http://localhost:8529"
Tospecifymultipletrustedorigins,theoptioncanbespecifiedmultipletimes.Alternativelyyoucanusethespecialvalue"*"totrustanyorigin:
--http.trusted-origin"*"
Notethatbrowserswillnotactuallyincludecredentialsorcookiesincross-originrequestsunlessexplicitlytoldtodoso:
WhenusingtheFetchAPIyouneedtosetthecredentialsoptiontoinclude.
fetch("./",{credentials:"include"}).then(/*…*/)
GeneralHTTPHandling
7
WhenusingXMLHttpRequestyouneedtosetthewithCredentialsoptiontotrue.
varxhr=newXMLHttpRequest();
xhr.open('GET','https://example.com/',true);
xhr.withCredentials=true;
xhr.send(null);
WhenusingjQueryyouneedtosetthexhrFieldsoption:
$.ajax({
url:'https://example.com',
xhrFields:{
withCredentials:true
}
});
HTTPmethodoverridingArangoDBprovidesastartupoption--http.allow-method-override.ThisoptioncanbesettoallowoverridingtheHTTPrequestmethod(e.g.GET,POST,PUT,DELETE,PATCH)ofarequestusingoneofthefollowingcustomHTTPheaders:
x-http-method-overridex-http-methodx-method-override
ThisallowsusingHTTPclientsthatdonotsupportall"common"HTTPmethodssuchasPUT,PATCHandDELETE.Italsoallowsbypassingproxiesandtoolsthatwouldotherwisejustletcertaintypesofrequests(e.g.GETandPOST)passthrough.
Enablingthisoptionmayimposeasecurityrisk,soitshouldonlybeusedinverycontrolledenvironments.Thusthedefaultvalueforthisoptionisfalse(nomethodoverridingallowed).Youneedtoenableitexplicitlyifyouwanttousethisfeature.
GeneralHTTPHandling
8
HTTPInterfaceFollowingyouhaveArangoDB'sHTTPInterfaceforDocuments,Databases,Edgesandmore.
TherearealsosomeexamplesprovidedforeveryAPIaction.
YoumayalsousetheinteractiveSwaggerdocumentationintheArangoDBwebinterfacetoexploretheAPIcallsbelow.
HTTPInterface
9
HTTPInterfaceforDatabases
AddressofaDatabase
AnyoperationtriggeredviaArangoDB'sHTTPRESTAPIisexecutedinthecontextofexactlyonedatabase.Toexplicitlyspecifythedatabaseinarequest,therequestURImustcontainthedatabasenameinfrontoftheactualpath:
http://localhost:8529/_db/mydb/...
where...istheactualpathtotheaccessedresource.Intheexample,theresourcewillbeaccessedinthecontextofthedatabasemydb.ActualURLsinthecontextofmydbcouldlooklikethis:
http://localhost:8529/_db/mydb/_api/version
http://localhost:8529/_db/mydb/_api/document/test/12345
http://localhost:8529/_db/mydb/myapp/get
Databases
10
Database-to-EndpointMappingIfadatabasenameispresentintheURIasabove,ArangoDBwillconsultthedatabase-to-endpointmappingforthecurrentendpoint,andvalidateifaccesstothedatabaseisallowedontheendpoint.Iftheendpointisnotrestrictedtoanarrayofdatabases,ArangoDBwillcontinuewiththeregularauthenticationprocedure.Iftheendpointisrestrictedtoanarrayofspecifieddatabases,ArangoDBwillcheckiftherequesteddatabaseisinthearray.Ifnot,therequestwillbeturneddowninstantly.Ifyes,thenArangoDBwillcontinuewiththeregularauthenticationprocedure.
IftherequestURIwashttp://localhost:8529/_db/mydb/...,thentherequesttomydbwillbeallowed(ordisallowed)inthefollowingsituations:
Endpoint-to-databasemappingAccessto*mydb*allowed?
-----------------------------------------------------
[]yes
["_system"]no
["_system","mydb"]yes
["mydb"]yes
["mydb","_system"]yes
["test1","test2"]no
IncasenodatabasenameisspecifiedintherequestURI,ArangoDBwillderivethedatabasenamefromtheendpoint-to-databasemappingoftheendpointtheconnectionwascominginon.
Iftheendpointisnotrestrictedtoanarrayofdatabases,ArangoDBwillassumethe_systemdatabase.Iftheendpointisrestrictedtooneormultipledatabases,ArangoDBwillassumethefirstnamefromthearray.
Followingisanoverviewofwhichdatabasenamewillbeassumedfordifferentendpoint-to-databasemappingsincasenodatabasenameisspecifiedintheURI:
Endpoint-to-databasemappingDatabase
------------------------------------
[]_system
["_system"]_system
["_system","mydb"]_system
["mydb"]mydb
["mydb","_system"]mydb
To-Endpoint
11
DatabaseManagementThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingdatabases.
TheHTTPinterfacefordatabasesprovidesoperationstocreateanddropindividualdatabases.ThesearemappedtothestandardHTTPmethodsPOSTandDELETE.ThereisalsotheGETmethodtoretrieveanarrayofexistingdatabases.
Pleasenotethatalldatabasemanagementoperationscanonlybeaccessedviathedefaultdatabase(_system)andnoneoftheotherdatabases.
ManagingDatabasesusingHTTP
Informationofthedatabase
retrievesinformationaboutthecurrentdatabase
GET/_api/database/current
Retrievesinformationaboutthecurrentdatabase
TheresponseisaJSONobjectwiththefollowingattributes:
name:thenameofthecurrentdatabase
id:theidofthecurrentdatabase
path:thefilesystempathofthecurrentdatabase
isSystem:whetherornotthecurrentdatabaseisthe_systemdatabase
Example:
shell>curl--dump-http://localhost:8529/_api/database/current
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":{
"name":"_system",
"id":"1",
"path":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/databases/database-1",
"isSystem":true
}
}
ReturnCodes
200:isreturnediftheinformationwasretrievedsuccessfully.400:isreturnediftherequestisinvalid.404:isreturnedifthedatabasecouldnotbefound.
Examples
shell>curl--dump-http://localhost:8529/_api/database/current
HTTP/1.1200OK
content-type:application/json;charset=utf-8
Management
12
x-content-type-options:nosniff
showresponsebody
Listofaccessibledatabases
retrievesalistofalldatabasesthecurrentusercanaccess
GET/_api/database/user
Retrievesthelistofalldatabasesthecurrentusercanaccesswithoutspecifyingadifferentusernameorpassword.
Example:
shell>curl--dump-http://localhost:8529/_api/database/user
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":[
"_system"
]
}
ReturnCodes
200:isreturnedifthelistofdatabasewascompiledsuccessfully.400:isreturnediftherequestisinvalid.
Examples
shell>curl--dump-http://localhost:8529/_api/database/user
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Listofdatabases
retrievesalistofallexistingdatabases
GET/_api/database
Retrievesthelistofallexistingdatabases
Note:retrievingthelistofdatabasesisonlypossiblefromwithinthe_systemdatabase.
Note:YoushouldusetheGETuserAPItofetchthelistoftheavailabledatabasesnow.
Example:
shell>curl--dump-http://localhost:8529/_api/database
Management
13
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":[
"_system"
]
}
ReturnCodes
200:isreturnedifthelistofdatabasewascompiledsuccessfully.400:isreturnediftherequestisinvalid.403:isreturnediftherequestwasnotexecutedinthe_systemdatabase.
Examples
shell>curl--dump-http://localhost:8529/_api/database
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Createdatabase
createsanewdatabase
POST/_api/database
AJSONobjectwiththesepropertiesisrequired:
name:Hastocontainavaliddatabasename.users:Hastobeanarrayofuserobjectstoinitiallycreateforthenewdatabase.Userinformationwillnotbechangedforusersthatalreadyexist.Ifusersisnotspecifiedordoesnotcontainanyusers,adefaultuserrootwillbecreatedwithanemptystringpassword.Thisensuresthatthenewdatabasewillbeaccessibleafteritiscreated.Eachuserobjectcancontainthefollowingattributes:
username:Loginnameoftheusertobecreatedpasswd:Theuserpasswordasastring.Ifnotspecified,itwilldefaulttoanemptystring.active:Aflagindicatingwhethertheuseraccountshouldbeactivatedornot.Thedefaultvalueistrue.Ifsettofalse,theuserwon'tbeabletologintothedatabase.extra:AJSONobjectwithextrauserinformation.ThedatacontainedinextrawillbestoredfortheuserbutnotbeinterpretedfurtherbyArangoDB.
Createsanewdatabase
TheresponseisaJSONobjectwiththeattributeresultsettotrue.
Note:creatinganewdatabaseisonlypossiblefromwithinthe_systemdatabase.
Example:Creatingadatabasenamedexample.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/database<<EOF
{
"name":"example"
}
Management
14
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":201,
"result":true
}
Example:Creatingadatabasenamedmydbwithtwousers.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/database<<EOF
{
"name":"mydb",
"users":[
{
"username":"admin",
"passwd":"secret",
"active":true
},
{
"username":"tester",
"passwd":"test001",
"active":false
}
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":201,
"result":true
}
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/database<<EOF
{
"name":"example"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyCreatingadatabasenamedmydbwithtwousers.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/database<<EOF
{
"name":"mydb",
"users":[
{
Management
15
"username":"admin",
"passwd":"secret",
"active":true
},
{
"username":"tester",
"passwd":"test001",
"active":false
}
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Dropdatabase
dropanexistingdatabase
DELETE/_api/database/{database-name}
PathParameters
database-name(required):Thenameofthedatabase
Dropsthedatabasealongwithalldatastoredinit.
Note:droppingadatabaseisonlypossiblefromwithinthe_systemdatabase.The_systemdatabaseitselfcannotbedropped.
Example:
shell>curl-XDELETE--dump-http://localhost:8529/_api/database/example
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":true
}
ReturnCodes
200:isreturnedifthedatabasewasdroppedsuccessfully.400:isreturnediftherequestismalformed.403:isreturnediftherequestwasnotexecutedinthe_systemdatabase.404:isreturnedifthedatabasecouldnotbefound.
Examples
shell>curl-XDELETE--dump-http://localhost:8529/_api/database/example
HTTP/1.1200OK
content-type:application/json;charset=utf-8
Management
16
x-content-type-options:nosniff
showresponsebody
Management
17
NotesonDatabasesPleasekeepinmindthateachdatabasecontainsitsownsystemcollections,whichneedtosetupwhenadatabaseiscreated.Thiswillmakethecreationofadatabasetakeawhile.Replicationisconfiguredonaper-databaselevel,meaningthatanyreplicationloggingorapplyingfortheanewdatabasemustbeconfiguredexplicitlyafteranewdatabasehasbeencreated.Foxxapplicationsarealsoavailableonlyinthecontextofthedatabasetheyhavebeeninstalledin.AnewdatabasewillonlyprovideaccesstothesystemapplicationsshippedwithArangoDB(thatisthewebinterfaceatthemoment)andnootherFoxxapplicationsuntiltheyareexplicitlyinstalledfortheparticulardatabase.
Database
ArangoDBcanhandlemultipledatabasesinthesameserverinstance.Databasescanbeusedtologicallygroupandseparatedata.AnArangoDBdatabaseconsistsofcollectionsanddedicateddatabase-specificworkerprocesses.Adatabasecontainsitsowncollections(whichcannotbeaccessedfromotherdatabases),Foxxapplicationsandreplicationloggersandappliers.EachArangoDBdatabasecontainsitsownsystemcollections(e.g._users,_graphs,...).
TherewillalwaysbeatleastonedatabaseinArangoDB.Thisisthedefaultdatabasenamed_system.Thisdatabasecannotbedroppedandprovidesspecialoperationsforcreating,droppingandenumeratingdatabases.Userscancreateadditionaldatabasesandgivethemuniquenamestoaccessthemlater.Databasemanagementoperationscannotbeinitiatedfromoutofuser-defineddatabases.
WhenArangoDBisaccessedviaitsHTTPRESTAPI,thedatabasenameisreadfromthefirstpartoftherequestURIpath(e.g./_db/_system/...).IftherequestURIdoesnotcontainadatabasename,thedatabasenameisautomaticallydeterminedbythealgorithmdescribedinDatabase-to-EndpointMapping.
DatabaseName
AsingleArangoDBinstancecanhandlemultipledatabasesinparallel.Whenmultipledatabasesareused,eachdatabasemustbegivenanuniquename.Thisnameisusedtouniquelyidentifyadatabase.ThedefaultdatabaseinArangoDBisnamedsystem.Thedatabasenameisastringconsistingofonlyletters,digitsandthe(underscore)and-(dash)characters.User-defineddatabasenamesmustalwaysstartwithaletter.Databasenamesarecase-sensitive.
DatabaseOrganization
AsingleArangoDBinstancecanhandlemultipledatabasesinparallel.Bydefault,therewillbeatleastonedatabasewhichisnamed_system.Databasesarephysicallystoredinseparatesub-directoriesunderneaththedatabasedirectory,whichitselfresidesintheinstance'sdatadirectory.
Eachdatabasehasitsownsub-directory,nameddatabase-.Thedatabasedirectorycontainssub-directoriesforthecollectionsofthedatabase,andafilenamedparameter.json.Thisfilecontainsthedatabaseidandname.
InanexampleArangoDBinstancewhichhastwodatabases,thefilesystemlayoutcouldlooklikethis:
data/#theinstance'sdatadirectory
databases/#sub-directorycontainingalldatabases'data
database-<id>/#sub-directoryforasingledatabase
parameter.json#filecontainingdatabaseidandname
collection-<id>/#directorycontainingdataaboutacollection
database-<id>/#sub-directoryforanotherdatabase
parameter.json#filecontainingdatabaseidandname
collection-<id>/#directorycontainingdataaboutacollection
collection-<id>/#directorycontainingdataaboutacollection
Foxxapplicationsarealsoorganizedindatabase-specificdirectoriesinsidetheapplicationpath.Thefilesystemlayoutcouldlooklikethis:
apps/#theinstance'sapplicationdirectory
system/#systemapplications(canbeignored)
databases/#sub-directorycontainingdatabase-specificapplications
<database-name>/#sub-directoryforasingledatabase
<app-name>#sub-directoryforasingleapplication
NotesonDatabases
18
<app-name>#sub-directoryforasingleapplication
<database-name>/#sub-directoryforanotherdatabase
<app-name>#sub-directoryforasingleapplication
`
NotesonDatabases
19
HTTPInterfaceforCollections
Collections
ThisisanintroductiontoArangoDB'sHTTPinterfaceforcollections.
Collection
Acollectionconsistsofdocuments.Itisuniquelyidentifiedbyitscollectionidentifier.Italsohasauniquenamethatclientsshouldusetoidentifyandaccessit.Collectionscanberenamed.Thiswillchangethecollectionname,butnotthecollectionidentifier.Collectionshaveatypethatisspecifiedbytheuserwhenthecollectioniscreated.Therearecurrentlytwotypes:documentandedge.Thedefaulttypeisdocument.
CollectionIdentifier
Acollectionidentifierletsyourefertoacollectioninadatabase.Itisastringvalueandisuniquewithinthedatabase.UptoincludingArangoDB1.1,thecollectionidentifierhasbeenaclient'sprimarymeanstoaccesscollections.StartingwithArangoDB1.2,clientsshouldinsteaduseacollection'suniquenametoaccessacollectioninsteadofitsidentifier.ArangoDBcurrentlyuses64bitunsignedintegervaluestomaintaincollectionidsinternally.Whenreturningcollectionidstoclients,ArangoDBwillputthemintoastringtoensurethecollectionidisnotclippedbyclientsthatdonotsupportbigintegers.ClientsshouldtreatthecollectionidsreturnedbyArangoDBasopaquestringswhentheystoreoruseitlocally.
Note:collectionidshavebeenreturnedasintegersuptoincludingArangoDB1.1
CollectionName
Acollectionnameidentifiesacollectioninadatabase.Itisastringandisuniquewithinthedatabase.Unlikethecollectionidentifieritissuppliedbythecreatorofthecollection.Thecollectionnamemustconsistofletters,digits,andthe_(underscore)and-(dash)charactersonly.PleaserefertoNamingConventionsinArangoDBformoreinformationonvalidcollectionnames.
KeyGenerator
ArangoDBallowsusingkeygeneratorsforeachcollection.Keygeneratorshavethepurposeofauto-generatingvaluesforthe_keyattributeofadocumentifnonewasspecifiedbytheuser.Bydefault,ArangoDBwillusethetraditionalkeygenerator.Thetraditionalkeygeneratorwillauto-generatekeyvaluesthatarestringswithever-increasingnumbers.Theincrementvaluesitusesarenon-deterministic.
Contrary,theautoincrementkeygeneratorwillauto-generatedeterministickeyvalues.Boththestartvalueandtheincrementvaluecanbedefinedwhenthecollectioniscreated.Thedefaultstartvalueis0andthedefaultincrementis1,meaningthekeyvaluesitwillcreatebydefaultare:
1,2,3,4,5,...
Whencreatingacollectionwiththeautoincrementkeygeneratorandanincrementof5,thegeneratedkeyswouldbe:
1,6,11,16,21,...
Theauto-incrementvaluesareincreasedandhandedoutoneachdocumentinsertattempt.Evenifaninsertfails,theauto-incrementvalueisneverrolledback.Thatmeanstheremayexistgapsinthesequenceofassignedauto-incrementvaluesifinsertsfails.
Thebasicoperations(create,read,update,delete)fordocumentsaremappedtothestandardHTTPmethods(POST,GET,PUT,DELETE).
AddressofaCollection
AllcollectionsinArangoDBhaveanuniqueidentifierandauniquename.ArangoDBinternallyusesthecollection'suniqueidentifiertolookupcollections.ThisidentifierhoweverismanagedbyArangoDBandtheuserhasnocontroloverit.Inordertoallowusersusetheirownnames,eachcollectionalsohasauniquename,whichisspecifiedbytheuser.Toaccessacollectionfromtheuserperspective,the
Collections
20
collectionnameshouldbeused,i.e.:
http://server:port/_api/collection/collection-name
Forexample:Assumethatthecollectionidentifieris7254820andthecollectionnameisdemo,thentheURLofthatcollectionis:
http://localhost:8529/_api/collection/demo
Collections
21
CreatingandDeletingCollections
Createcollection
createsacollection
POST/_api/collection
AJSONobjectwiththesepropertiesisrequired:
journalSize:Themaximalsizeofajournalordatafileinbytes.Thevaluemustbeatleast1048576(1MiB).(Thedefaultisaconfigurationparameter)ThisoptionismeaningfulfortheMMFilesstorageengineonly.replicationFactor:(Thedefaultis1):inacluster,thisattributedetermineshowmanycopiesofeachshardarekeptondifferentDBServers.Thevalue1meansthatonlyonecopy(nosynchronousreplication)iskept.Avalueofkmeansthatk-1replicasarekept.AnytwocopiesresideondifferentDBServers.Replicationbetweenthemissynchronous,thatis,everywriteoperationtothe"leader"copywillbereplicatedtoall"follower"replicas,beforethewriteoperationisreportedsuccessful.Ifaserverfails,thisisdetectedautomaticallyandoneoftheserversholdingcopiestakeover,usuallywithoutanerrorbeingreported.keyOptions:
allowUserKeys:ifsettotrue,thenitisallowedtosupplyownkeyvaluesinthe_keyattributeofadocument.Ifsettofalse,thenthekeygeneratorwillsolelyberesponsibleforgeneratingkeysandsupplyingownkeyvaluesinthe_keyattributeofdocumentsisconsideredanerror.type:specifiesthetypeofthekeygenerator.Thecurrentlyavailablegeneratorsaretraditionalandautoincrement.increment:incrementvalueforautoincrementkeygenerator.Notusedforotherkeygeneratortypes.offset:Initialoffsetvalueforautoincrementkeygenerator.Notusedforotherkeygeneratortypes.
name:Thenameofthecollection.waitForSync:Iftruethenthedataissynchronizedtodiskbeforereturningfromadocumentcreate,update,replaceorremovaloperation.(default:false)doCompact:whetherornotthecollectionwillbecompacted(defaultistrue)ThisoptionismeaningfulfortheMMFilesstorageengineonly.isVolatile:Iftruethenthecollectiondataiskeptin-memoryonlyandnotmadepersistent.Unloadingthecollectionwillcausethecollectiondatatobediscarded.Stoppingorre-startingtheserverwillalsocausefulllossofdatainthecollection.SettingthisoptionwillmaketheresultingcollectionbeslightlyfasterthanregularcollectionsbecauseArangoDBdoesnotenforceanysynchronizationtodiskanddoesnotcalculateanyCRCchecksumsfordatafiles(astherearenodatafiles).Thisoptionshouldthereforebeusedforcache-typecollectionsonly,andnotfordatathatcannotbere-createdotherwise.(Thedefaultisfalse)ThisoptionismeaningfulfortheMMFilesstorageengineonly.shardKeys:(Thedefaultis["_key"]):inacluster,thisattributedetermineswhichdocumentattributesareusedtodeterminethetargetshardfordocuments.Documentsaresenttoshardsbasedonthevaluesoftheirshardkeyattributes.Thevaluesofallshardkeyattributesinadocumentarehashed,andthehashvalueisusedtodeterminethetargetshard.Note:Valuesofshardkeyattributescannotbechangedonceset.Thisoptionismeaninglessinasingleserversetup.numberOfShards:(Thedefaultis1):inacluster,thisvaluedeterminesthenumberofshardstocreateforthecollection.Inasingleserversetup,thisoptionismeaningless.isSystem:Iftrue,createasystemcollection.Inthiscasecollection-nameshouldstartwithanunderscore.Endusersshouldnormallycreatenon-systemcollectionsonly.APIimplementorsmayberequiredtocreatesystemcollectionsinveryspecialoccasions,butnormallyaregularcollectionwilldo.(Thedefaultisfalse)type:(Thedefaultis2):thetypeofthecollectiontocreate.Thefollowingvaluesfortypearevalid:
2:documentcollection3:edgescollection
indexBuckets:Thenumberofbucketsintowhichindexesusingahashtablearesplit.Thedefaultis16andthisnumberhastobeapowerof2andlessthanorequalto1024.Forverylargecollectionsoneshouldincreasethistoavoidlongpauseswhenthehashtablehastobeinitiallybuiltorresized,sincebucketsareresizedindividuallyandcanbeinitiallybuiltinparallel.Forexample,64mightbeasensiblevalueforacollectionwith100000000documents.Currently,onlytheedgeindexrespectsthisvalue,butotherindextypesmightfollowinfutureArangoDBversions.Changes(seebelow)areappliedwhenthecollectionisloadedthenexttime.ThisoptionismeaningfulfortheMMFilesstorageengineonly.distributeShardsLike:(Thedefaultis""):inanenterprisecluster,thisattributebindsthespecificsofshardingforthenewlycreatedcollectiontofollowthatofaspecifiedexistingcollection.Note:Usingthisparameterhasconsequencesfortheprototypecollection.Itcannolongerbedropped,beforeshardingimitatingcollectionsaredropped.Equally,backupsandrestoresofimitating
Creating
22
collectionsalonewillgeneratewarnings,whichcanbeoverridden,aboutmissingshardingprototype.
Createsanewcollectionwithagivenname.Therequestmustcontainanobjectwiththefollowingattributes.
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/collection<<EOF
{
"name":"testCollectionBasics"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"code":200,
"error":false,
"status":3,
"statusString":"loaded",
"name":"testCollectionBasics",
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"type":2,
"indexBuckets":8,
"globallyUniqueId":"h68719E5AC6E7/9999",
"doCompact":true,
"waitForSync":false,
"id":"9999",
"isSystem":false,
"journalSize":33554432,
"isVolatile":false
}
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/collection<<EOF
{
"name":"testCollectionEdges",
"type":3
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"code":200,
"error":false,
"status":3,
"statusString":"loaded",
"name":"testCollectionEdges",
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"type":3,
"indexBuckets":8,
"globallyUniqueId":"h68719E5AC6E7/10002",
"doCompact":true,
"waitForSync":false,
"id":"10002",
"isSystem":false,
"journalSize":33554432,
"isVolatile":false
}
Creating
23
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/collection<<EOF
{
"name":"testCollectionUsers",
"keyOptions":{
"type":"autoincrement",
"increment":5,
"allowUserKeys":true
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"code":200,
"error":false,
"status":3,
"statusString":"loaded",
"name":"testCollectionUsers",
"keyOptions":{
"type":"autoincrement",
"allowUserKeys":true,
"offset":0,
"increment":5,
"lastValue":0
},
"type":2,
"indexBuckets":8,
"globallyUniqueId":"h68719E5AC6E7/10013",
"doCompact":true,
"waitForSync":false,
"id":"10013",
"isSystem":false,
"journalSize":33554432,
"isVolatile":false
}
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/collection<<EOF
{
"name":"testCollectionBasics"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/collection<<EOF
{
"name":"testCollectionUsers",
"keyOptions":{
"type":"autoincrement",
"increment":5,
"allowUserKeys":true
}
}
EOF
Creating
24
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Dropsacollection
dropsacollection
DELETE/_api/collection/{collection-name}
PathParameters
collection-name(required):Thenameofthecollectiontodrop.
QueryParameters
isSystem(optional):Whetherornotthecollectiontodropisasystemcollection.Thisparametermustbesettotrueinordertodropasystemcollection.
Dropsthecollectionidentifiedbycollection-name.
Ifthecollectionwassuccessfullydropped,anobjectisreturnedwiththefollowingattributes:
error:false
id:Theidentifierofthedroppedcollection.
Example:Usinganidentifier:
shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/10020
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"code":200,
"error":false,
"id":"10020"
}
Example:Usinganame:
shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/products1
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"code":200,
"error":false,
"id":"10027"
}
Creating
25
Example:Droppingasystemcollection
shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/_example?isSystem=true
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"code":200,
"error":false,
"id":"10034"
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Usinganidentifier:
shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/10020
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsinganame:
shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/products1
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyDroppingasystemcollection
shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/_example?
isSystem=true
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Truncatecollection
truncatesacollection
Creating
26
PUT/_api/collection/{collection-name}/truncate
PathParameters
collection-name(required):Thenameofthecollection.
Removesalldocumentsfromthecollection,butleavestheindexesintact.
Example:
shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/truncate
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/truncate
{
"code":200,
"error":false,
"status":3,
"name":"products",
"type":2,
"globallyUniqueId":"h68719E5AC6E7/10462",
"isSystem":false,
"id":"10462"
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/truncate
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/truncate
showresponsebody
Creating
27
GettingInformationaboutaCollection
Returninformationaboutacollection
returnsacollection
GET/_api/collection/{collection-name}
PathParameters
collection-name(required):Thenameofthecollection.
Theresultisanobjectdescribingthecollectionwiththefollowingattributes:
id:Theidentifierofthecollection.
name:Thenameofthecollection.
status:Thestatusofthecollectionasnumber.
1:newborncollection2:unloaded3:loaded4:intheprocessofbeingunloaded5:deleted6:loading
Everyotherstatusindicatesacorruptedcollection.
type:Thetypeofthecollectionasnumber.
2:documentcollection(normalcase)3:edgescollection
isSystem:Iftruethenthecollectionisasystemcollection.
ReturnCodes
404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Readpropertiesofacollection
readsthepropertiesofthespecifiedcollection
GET/_api/collection/{collection-name}/properties
PathParameters
collection-name(required):Thenameofthecollection.
Inadditiontotheabove,theresultwillalwayscontainthewaitForSyncattribute,andthedoCompact,journalSize,andisVolatileattributesfortheMMFilesstorageengine.Thisisachievedbyforcingaloadoftheunderlyingcollection.
waitForSync:Iftruethencreating,changingorremovingdocumentswillwaituntilthedatahasbeensynchronizedtodisk.
doCompact:Whetherornotthecollectionwillbecompacted.ThisoptionisonlypresentfortheMMFilesstorageengine.
journalSize:Themaximalsizesettingforjournals/datafilesinbytes.ThisoptionisonlypresentfortheMMFilesstorageengine.
keyOptions:JSONobjectwhichcontainskeygenerationoptions:
type:specifiesthetypeofthekeygenerator.Thecurrentlyavailablegeneratorsaretraditionalandautoincrement.allowUserKeys:ifsettotrue,thenitisallowedtosupplyownkeyvaluesinthe_keyattributeofadocument.Ifsettofalse,thenthekeygeneratorissolelyresponsibleforgeneratingkeysandsupplyingownkeyvaluesinthe_keyattributeofdocumentsisconsideredanerror.
isVolatile:IftruethenthecollectiondatawillbekeptinmemoryonlyandArangoDBwillnotwriteorsyncthedatatodisk.ThisoptionisonlypresentfortheMMFilesstorageengine.
GettingInformation
28
Inaclustersetup,theresultwillalsocontainthefollowingattributes:
numberOfShards:thenumberofshardsofthecollection.
shardKeys:containsthenamesofdocumentattributesthatareusedtodeterminethetargetshardfordocuments.
replicationFactor:containshowmanycopiesofeachshardarekeptondifferentDBServers.
Example:Usinganidentifier:
shell>curl--dump-http://localhost:8529/_api/collection/10401/properties
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/10401/properties
{
"code":200,
"error":false,
"status":3,
"statusString":"loaded",
"name":"products",
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"type":2,
"indexBuckets":8,
"globallyUniqueId":"h68719E5AC6E7/10401",
"doCompact":true,
"waitForSync":true,
"id":"10401",
"isSystem":false,
"journalSize":33554432,
"isVolatile":false
}
Example:Usinganame:
shell>curl--dump-http://localhost:8529/_api/collection/products/properties
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/properties
{
"code":200,
"error":false,
"status":3,
"statusString":"loaded",
"name":"products",
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"type":2,
"indexBuckets":8,
"globallyUniqueId":"h68719E5AC6E7/10409",
"doCompact":true,
"waitForSync":true,
"id":"10409",
GettingInformation
29
"isSystem":false,
"journalSize":33554432,
"isVolatile":false
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Usinganidentifier:
shell>curl--dump-http://localhost:8529/_api/collection/10401/properties
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/10401/properties
showresponsebodyUsinganame:
shell>curl--dump-http://localhost:8529/_api/collection/products/properties
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/properties
showresponsebody
Returnnumberofdocumentsinacollection
Countsthedocumentsinacollection
GET/_api/collection/{collection-name}/count
PathParameters
collection-name(required):Thenameofthecollection.
Inadditiontotheabove,theresultalsocontainsthenumberofdocuments.Notethatthiswillalwaysloadthecollectionintomemory.
count:Thenumberofdocumentsinsidethecollection.
Example:Requestingthenumberofdocuments:
shell>curl--dump-http://localhost:8529/_api/collection/products/count
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/count
{
"code":200,
GettingInformation
30
"error":false,
"statusString":"loaded",
"name":"products",
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":10367
},
"journalSize":33554432,
"isVolatile":false,
"status":3,
"count":100,
"doCompact":true,
"globallyUniqueId":"h68719E5AC6E7/10065",
"type":2,
"indexBuckets":8,
"waitForSync":true,
"id":"10065",
"isSystem":false
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Requestingthenumberofdocuments:
shell>curl--dump-http://localhost:8529/_api/collection/products/count
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/count
showresponsebody
Returnstatisticsforacollection
Fetchthestatisticsofacollection
GET/_api/collection/{collection-name}/figures
PathParameters
collection-name(required):Thenameofthecollection.
Inadditiontotheabove,theresultalsocontainsthenumberofdocumentsandadditionalstatisticalinformationaboutthecollection.Note:Thiswillalwaysloadthecollectionintomemory.
Note:collectiondatathatarestoredinthewrite-aheadlogonlyarenotreportedintheresults.Whenthewrite-aheadlogiscollected,documentsmightbeaddedtojournalsanddatafilesofthecollection,whichmaymodifythefiguresofthecollection.
Additionally,thefilesizesofcollectionandindexparameterJSONfilesarenotreported.Thesefilesshouldnormallyhaveasizeofafewbyteseach.PleasealsonotethatthefileSizevaluesarereportedinbytesandreflectthelogicalfilesizes.Somefilesystemsmayuseoptimisations(e.g.sparsefiles)sothattheactualphysicalfilesizeissomewhatdifferent.Directoriesandsub-directoriesmayalsorequirespaceinthefilesystem,butthisspaceisnotreportedinthefileSizeresults.
Thatmeansthatthefiguresreporteddonotreflecttheactualdiskusageofthecollectionwith100%accuracy.TheactualdiskusageofacollectionisnormallyslightlyhigherthanthesumofthereportedfileSizevalues.StillthesumofthefileSizevaluescanstillbeusedasalowerboundapproximationofthediskusage.
AjsondocumentwiththesePropertiesisreturned:
GettingInformation
31
HTTP200
Returnsinformationaboutthecollection:
count:Thenumberofdocumentscurrentlypresentinthecollection.journalSize:Themaximalsizeofajournalordatafileinbytes.figures:
datafiles:count:Thenumberofdatafiles.fileSize:Thetotalfilesizeofdatafiles(inbytes).
uncollectedLogfileEntries:Thenumberofmarkersinthewrite-aheadlogforthiscollectionthathavenotbeentransferredtojournalsordatafiles.documentReferences:ThenumberofreferencestodocumentsindatafilesthatJavaScriptcodecurrentlyholds.Thisinformationcanbeusedfordebuggingcompactionandunloadissues.compactionStatus:
message:Theactionthatwasperformedwhenthecompactionwaslastrunforthecollection.Thisinformationcanbeusedfordebuggingcompactionissues.time:Thepointintimethecompactionforthecollectionwaslastexecuted.Thisinformationcanbeusedfordebuggingcompactionissues.
compactors:count:Thenumberofcompactorfiles.fileSize:Thetotalfilesizeofallcompactorfiles(inbytes).
dead:count:Thenumberofdeaddocuments.Thisincludesdocumentversionsthathavebeendeletedorreplacedbyanewerversion.Documentsdeletedorreplacedthatarecontainedthewrite-aheadlogonlyarenotreportedinthisfigure.deletion:Thetotalnumberofdeletionmarkers.Deletionmarkersonlycontainedinthewrite-aheadlogarenotreportinginthisfigure.size:Thetotalsizeinbytesusedbyalldeaddocuments.
indexes:count:Thetotalnumberofindexesdefinedforthecollection,includingthepre-definedindexes(e.g.primaryindex).size:Thetotalmemoryallocatedforindexesinbytes.
readcache:count:Thenumberofrevisionsofthiscollectionstoredinthedocumentrevisionscache.size:Thememoryusedforstoringtherevisionsofthiscollectioninthedocumentrevisionscache(inbytes).Thisfiguredoesnotincludethedocumentdatabutonlymappingsfromdocumentrevisionidstocacheentrylocations.
waitingFor:Anoptionalstringvaluethatcontainsinformationaboutwhichobjecttypeisattheheadofthecollection'scleanupqueue.Thisinformationcanbeusedfordebuggingcompactionandunloadissues.alive:
count:Thenumberofcurrentlyactivedocumentsinalldatafilesandjournalsofthecollection.Documentsthatarecontainedinthewrite-aheadlogonlyarenotreportedinthisfigure.size:Thetotalsizeinbytesusedbyallactivedocumentsofthecollection.Documentsthatarecontainedinthewrite-aheadlogonlyarenotreportedinthisfigure.
lastTick:Thetickofthelastmarkerthatwasstoredinajournalofthecollection.Thismightbe0ifthecollectiondoesnotyethaveajournal.journals:
count:Thenumberofjournalfiles.fileSize:Thetotalfilesizeofalljournalfiles(inbytes).
revisions:count:Thenumberofrevisionsofthiscollectionmanagedbythestorageengine.size:Thememoryusedforstoringtherevisionsofthiscollectioninthestorageengine(inbytes).Thisfiguredoesnotincludethedocumentdatabutonlymappingsfromdocumentrevisionidstostorageenginedatafilepositions.
Example:Usinganidentifierandrequestingthefiguresofthecollection:
GettingInformation
32
shell>curl--dump-http://localhost:8529/_api/collection/products/figures
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/figures
{
"code":200,
"error":false,
"statusString":"loaded",
"name":"products",
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":10379
},
"journalSize":33554432,
"isVolatile":false,
"isSystem":false,
"status":3,
"count":1,
"figures":{
"indexes":{
"count":1,
"size":32128
},
"documentReferences":0,
"waitingFor":"-",
"alive":{
"count":1,
"size":72
},
"dead":{
"count":0,
"size":0,
"deletion":0
},
"compactionStatus":{
"message":"skippedcompactionbecausecollectionhasnodatafiles",
"time":"2018-01-25T19:13:38Z",
"count":0,
"filesCombined":0,
"bytesRead":0,
"bytesWritten":0
},
"datafiles":{
"count":0,
"fileSize":0
},
"journals":{
"count":1,
"fileSize":33554432
},
"compactors":{
"count":0,
"fileSize":0
},
"revisions":{
"count":1,
"size":48192
},
"lastTick":10381,
"uncollectedLogfileEntries":0
},
"doCompact":true,
"globallyUniqueId":"h68719E5AC6E7/10375",
"type":2,
"indexBuckets":8,
"waitForSync":false,
"id":"10375"
}
ReturnCodes
GettingInformation
33
200:Returnsinformationaboutthecollection:
ResponseBody
count:Thenumberofdocumentscurrentlypresentinthecollection.journalSize:Themaximalsizeofajournalordatafileinbytes.figures:
datafiles:count:Thenumberofdatafiles.fileSize:Thetotalfilesizeofdatafiles(inbytes).uncollectedLogfileEntries:Thenumberofmarkersinthewrite-aheadlogforthiscollectionthathavenotbeentransferredtojournalsordatafiles.lastTick:Thetickofthelastmarkerthatwasstoredinajournalofthecollection.Thismightbe0ifthecollectiondoesnotyethaveajournal.compactionStatus:message:Theactionthatwasperformedwhenthecompactionwaslastrunforthecollection.Thisinformationcanbeusedfordebuggingcompactionissues.time:Thepointintimethecompactionforthecollectionwaslastexecuted.Thisinformationcanbeusedfordebuggingcompactionissues.dead:count:Thenumberofdeaddocuments.Thisincludesdocumentversionsthathavebeendeletedorreplacedbyanewerversion.Documentsdeletedorreplacedthatarecontainedthewrite-aheadlogonlyarenotreportedinthisfigure.deletion:Thetotalnumberofdeletionmarkers.Deletionmarkersonlycontainedinthewrite-aheadlogarenotreportinginthisfigure.size:Thetotalsizeinbytesusedbyalldeaddocuments.compactors:count:Thenumberofcompactorfiles.fileSize:Thetotalfilesizeofallcompactorfiles(inbytes).readcache:count:Thenumberofrevisionsofthiscollectionstoredinthedocumentrevisionscache.size:Thememoryusedforstoringtherevisionsofthiscollectioninthedocumentrevisionscache(inbytes).Thisfiguredoesnotincludethedocumentdatabutonlymappingsfromdocumentrevisionidstocacheentrylocations.waitingFor:Anoptionalstringvaluethatcontainsinformationaboutwhichobjecttypeisattheheadofthecollection'scleanupqueue.Thisinformationcanbeusedfordebuggingcompactionandunloadissues.alive:count:Thenumberofcurrentlyactivedocumentsinalldatafilesandjournalsofthecollection.Documentsthatarecontainedinthewrite-aheadlogonlyarenotreportedinthisfigure.size:Thetotalsizeinbytesusedbyallactivedocumentsofthecollection.Documentsthatarecontainedinthewrite-aheadlogonlyarenotreportedinthisfigure.documentReferences:ThenumberofreferencestodocumentsindatafilesthatJavaScriptcodecurrentlyholds.Thisinformationcanbeusedfordebuggingcompactionandunloadissues.indexes:count:Thetotalnumberofindexesdefinedforthecollection,includingthepre-definedindexes(e.g.primaryindex).size:Thetotalmemoryallocatedforindexesinbytes.journals:count:Thenumberofjournalfiles.fileSize:Thetotalfilesizeofalljournalfiles(inbytes).revisions:count:Thenumberofrevisionsofthiscollectionmanagedbythestorageengine.size:Thememoryusedforstoringtherevisionsofthiscollectioninthestorageengine(inbytes).Thisfiguredoesnotincludethedocumentdatabutonlymappingsfromdocumentrevisionidstostorageenginedatafilepositions.
shell>curl--dump-http://localhost:8529/_api/collection/products/figures
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
GettingInformation
34
location:/_api/collection/products/figures
showresponsebody
Returncollectionrevisionid
Retrievethecollectionsrevisionid
GET/_api/collection/{collection-name}/revision
PathParameters
collection-name(required):Thenameofthecollection.
Inadditiontotheabove,theresultwillalsocontainthecollection'srevisionid.Therevisionidisaserver-generatedstringthatclientscanusetocheckwhetherdatainacollectionhaschangedsincethelastrevisioncheck.
revision:Thecollectionrevisionidasastring.
Example:Retrievingtherevisionofacollection
shell>curl--dump-http://localhost:8529/_api/collection/products/revision
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/revision
{
"code":200,
"error":false,
"journalSize":33554432,
"isVolatile":false,
"isSystem":false,
"waitForSync":false,
"id":"10417",
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"revision":"0",
"indexBuckets":8,
"type":2,
"statusString":"loaded",
"name":"products",
"globallyUniqueId":"h68719E5AC6E7/10417",
"doCompact":true,
"status":3
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Retrievingtherevisionofacollection
shell>curl--dump-http://localhost:8529/_api/collection/products/revision
HTTP/1.1200OK
GettingInformation
35
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/revision
showresponsebody
Returnchecksumforthecollection
returnsachecksumforthespecifiedcollection
GET/_api/collection/{collection-name}/checksum
PathParameters
collection-name(required):Thenameofthecollection.
QueryParameters
withRevisions(optional):Whetherornottoincludedocumentrevisionidsinthechecksumcalculation.withData(optional):Whetherornottoincludedocumentbodydatainthechecksumcalculation.
Willcalculateachecksumofthemeta-data(keysandoptionallyrevisionids)andoptionallythedocumentdatainthecollection.
ThechecksumcanbeusedtocompareiftwocollectionsondifferentArangoDBinstancescontainthesamecontents.Thecurrentrevisionofthecollectionisreturnedtoosoonecanmakesurethechecksumsarecalculatedforthesamestateofdata.
Bydefault,thechecksumwillonlybecalculatedonthe_keysystemattributeofthedocumentscontainedinthecollection.Foredgecollections,thesystemattributes_fromand_towillalsobeincludedinthecalculation.
BysettingtheoptionalqueryparameterwithRevisionstotrue,thenrevisionids(_revsystemattributes)areincludedinthechecksumming.
ByprovidingtheoptionalqueryparameterwithDatawithavalueoftrue,theuser-defineddocumentattributeswillbeincludedinthecalculationtoo.Note:Includinguser-definedattributeswillmakethechecksummingslower.
TheresponseisaJSONobjectwiththefollowingattributes:
checksum:Thecalculatedchecksumasanumber.
revision:Thecollectionrevisionidasastring.
Note:thismethodisnotavailableinacluster.
Example:Retrievingthechecksumofacollection:
shell>curl--dump-http://localhost:8529/_api/collection/products/checksum
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/checksum
{
"code":200,
"error":false,
"globallyUniqueId":"h68719E5AC6E7/10041",
"isSystem":false,
"revision":"_WQ47VrK--_",
"type":2,
"checksum":"10263933996432733528",
"id":"10041",
"name":"products",
"status":3
}
GettingInformation
36
Example:Retrievingthechecksumofacollectionincludingthecollectiondata,butnottherevisions:
shell>curl--dump-http://localhost:8529/_api/collection/products/checksum?withRevisions=false&withData=true
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/checksum
{
"code":200,
"error":false,
"globallyUniqueId":"h68719E5AC6E7/10053",
"isSystem":false,
"revision":"_WQ47VsK--_",
"type":2,
"checksum":"9794134053781729250",
"id":"10053",
"name":"products",
"status":3
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Retrievingthechecksumofacollection:
shell>curl--dump-http://localhost:8529/_api/collection/products/checksum
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/checksum
showresponsebodyRetrievingthechecksumofacollectionincludingthecollectiondata,butnottherevisions:
shell>curl--dump-http://localhost:8529/_api/collection/products/checksum?
withRevisions=false&withData=true
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/checksum
showresponsebody
readsallcollections
returnsallcollections
GET/_api/collection
GettingInformation
37
QueryParameters
excludeSystem(optional):Whetherornotsystemcollectionsshouldbeexcludedfromtheresult.
Returnsanobjectwithanattributecollectionscontaininganarrayofallcollectiondescriptions.Thesameinformationisalsoavailableinthenamesasanobjectwiththecollectionnamesaskeys.
ByprovidingtheoptionalqueryparameterexcludeSystemwithavalueoftrue,allsystemcollectionswillbeexcludedfromtheresponse.
Example:Returninformationaboutallcollections:
shell>curl--dump-http://localhost:8529/_api/collection
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":[
{
"id":"28",
"name":"_statisticsRaw",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_statisticsRaw"
},
{
"id":"11",
"name":"_modules",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_modules"
},
{
"id":"45",
"name":"_queues",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_queues"
},
{
"id":"26",
"name":"_aqlfunctions",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_aqlfunctions"
},
{
"id":"60",
"name":"_appbundles",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_appbundles"
},
{
"id":"2",
"name":"_graphs",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_graphs"
},
{
GettingInformation
38
"id":"13",
"name":"_routing",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_routing"
},
{
"id":"47",
"name":"_jobs",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_jobs"
},
{
"id":"98",
"name":"animals",
"status":3,
"type":2,
"isSystem":false,
"globallyUniqueId":"h68719E5AC6E7/98"
},
{
"id":"43",
"name":"_frontend",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_frontend"
},
{
"id":"6",
"name":"_users",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_users"
},
{
"id":"33",
"name":"_statistics",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_statistics"
},
{
"id":"38",
"name":"_statistics15",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_statistics15"
},
{
"id":"55",
"name":"_apps",
"status":3,
"type":2,
"isSystem":true,
"globallyUniqueId":"_apps"
},
{
"id":"92",
"name":"demo",
"status":3,
"type":2,
"isSystem":false,
"globallyUniqueId":"h68719E5AC6E7/92"
}
]
}
ReturnCodes
GettingInformation
39
200:Thelistofcollections
Examples
Returninformationaboutallcollections:
shell>curl--dump-http://localhost:8529/_api/collection
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
GettingInformation
40
ModifyingaCollection
Loadcollection
loadsacollection
PUT/_api/collection/{collection-name}/load
PathParameters
collection-name(required):Thenameofthecollection.
Loadsacollectionintomemory.Returnsthecollectiononsuccess.
Therequestbodyobjectmightoptionallycontainthefollowingattribute:
count:Ifset,thiscontrolswhetherthereturnvalueshouldincludethenumberofdocumentsinthecollection.Settingcounttofalsemayspeeduploadingacollection.Thedefaultvalueforcountistrue.
Onsuccessanobjectwiththefollowingattributesisreturned:
id:Theidentifierofthecollection.
name:Thenameofthecollection.
count:Thenumberofdocumentsinsidethecollection.Thisisonlyreturnedifthecountinputparametersissettotrueorhasnotbeenspecified.
status:Thestatusofthecollectionasnumber.
type:Thecollectiontype.Validtypesare:
2:documentcollection3:edgescollection
isSystem:Iftruethenthecollectionisasystemcollection.
Example:
shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/load
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/load
{
"code":200,
"error":false,
"type":2,
"globallyUniqueId":"h68719E5AC6E7/10426",
"count":0,
"status":3,
"id":"10426",
"isSystem":false,
"name":"products"
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/load
Modifying
41
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/load
showresponsebody
Unloadcollection
unloadsacollection
PUT/_api/collection/{collection-name}/unload
PathParameters
collection-name(required):
Removesacollectionfrommemory.Thiscalldoesnotdeleteanydocuments.Youcanusethecollectionafterwards;inwhichcaseitwillbeloadedintomemory,again.Onsuccessanobjectwiththefollowingattributesisreturned:
id:Theidentifierofthecollection.
name:Thenameofthecollection.
status:Thestatusofthecollectionasnumber.
type:Thecollectiontype.Validtypesare:
2:documentcollection3:edgescollection
isSystem:Iftruethenthecollectionisasystemcollection.
Example:
shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/unload
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/unload
{
"code":200,
"error":false,
"status":4,
"name":"products",
"type":2,
"globallyUniqueId":"h68719E5AC6E7/10470",
"isSystem":false,
"id":"10470"
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/unload
HTTP/1.1200OK
Modifying
42
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/unload
showresponsebody
LoadIndexesintoMemory
LoadIndexesintoMemory
PUT/_api/collection/{collection-name}/loadIndexesIntoMemory
PathParameters
collection-name(required):
Thisroutetriestocacheallindexentriesofthiscollectionintothemainmemory.Thereforeititeratesoverallindexesofthecollectionandstorestheindexedvalues,nottheentiredocumentdata,inmemory.Alllookupsthatcouldbefoundinthecachearemuchfasterthanlookupsnotstoredinthecachesoyougetaniceperformanceboost.Itisalsoguaranteedthatthecacheisconsistentwiththestoreddata.
ForthetimebeingthisfunctionisonlyusefulonRocksDBstorageengine,asinMMFilesengineallindexesareinmemoryanyways.
OnRocksDBthisfunctionhonorsallmemorylimits,iftheindexesyouwanttoloadaresmallerthanyourmemorylimitthisfunctionguaranteesthatmostindexvaluesarecached.Iftheindexislargerthanyourmemorylimitthisfunctionwillfillupvaluesuptothislimitandforthetimebeingthereisnowaytocontrolwhichindexesofthecollectionshouldhavepriorityoverothers.
Onsucessthisfunctionreturnsanobjectwithattributeresultsettotrue
Example:
shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/loadIndexesIntoMemory
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/loadIndexesIntoMemory
{
"code":200,
"error":false,
"result":true
}
ReturnCodes
200:Iftheindexeshaveallbeenloaded400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
shell>curl-XPUT--dump-
http://localhost:8529/_api/collection/products/loadIndexesIntoMemory
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/loadIndexesIntoMemory
Modifying
43
showresponsebody
Changepropertiesofacollection
changesacollection
PUT/_api/collection/{collection-name}/properties
PathParameters
collection-name(required):Thenameofthecollection.
Changesthepropertiesofacollection.Expectsanobjectwiththeattribute(s)
waitForSync:Iftruethencreatingorchangingadocumentwillwaituntilthedatahasbeensynchronizedtodisk.
journalSize:Themaximalsizeofajournalordatafileinbytes.Thevaluemustbeatleast1048576(1MB).NotethatwhenchangingthejournalSizevalue,itwillonlyhaveaneffectforadditionaljournalsordatafilesthatarecreated.Alreadyexistingjournalsordatafileswillnotbeaffected.
Onsuccessanobjectwiththefollowingattributesisreturned:
id:Theidentifierofthecollection.
name:Thenameofthecollection.
waitForSync:Thenewvalue.
journalSize:Thenewvalue.
status:Thestatusofthecollectionasnumber.
type:Thecollectiontype.Validtypesare:
2:documentcollection3:edgescollection
isSystem:Iftruethenthecollectionisasystemcollection.
isVolatile:IftruethenthecollectiondatawillbekeptinmemoryonlyandArangoDBwillnotwriteorsyncthedatatodisk.
doCompact:Whetherornotthecollectionwillbecompacted.
keyOptions:JSONobjectwhichcontainskeygenerationoptions:
type:specifiesthetypeofthekeygenerator.Thecurrentlyavailablegeneratorsaretraditionalandautoincrement.allowUserKeys:ifsettotrue,thenitisallowedtosupplyownkeyvaluesinthe_keyattributeofadocument.Ifsettofalse,thenthekeygeneratorissolelyresponsibleforgeneratingkeysandsupplyingownkeyvaluesinthe_keyattributeofdocumentsisconsideredanerror.
Note:exceptforwaitForSync,journalSizeandname,collectionpropertiescannotbechangedonceacollectioniscreated.Torenameacollection,therenameendpointmustbeused.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/collection/products/properties<<EOF
{
"waitForSync":true
}
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/properties
{
"code":200,
"error":false,
Modifying
44
"status":3,
"statusString":"loaded",
"name":"products",
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"type":2,
"indexBuckets":8,
"globallyUniqueId":"h68719E5AC6E7/10443",
"doCompact":true,
"waitForSync":true,
"id":"10443",
"isSystem":false,
"journalSize":33554432,
"isVolatile":false
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/collection/products/properties<<EOF
{
"waitForSync":true
}
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/properties
showresponsebody
Renamecollection
renamesacollection
PUT/_api/collection/{collection-name}/rename
PathParameters
collection-name(required):Thenameofthecollectiontorename.
Renamesacollection.Expectsanobjectwiththeattribute(s)
name:Thenewname.
Itreturnsanobjectwiththeattributes
id:Theidentifierofthecollection.
name:Thenewnameofthecollection.
status:Thestatusofthecollectionasnumber.
type:Thecollectiontype.Validtypesare:
2:documentcollection3:edgescollection
Modifying
45
isSystem:Iftruethenthecollectionisasystemcollection.
Ifrenamingthecollectionsucceeds,thenthecollectionisalsorenamedinallgraphdefinitionsinsidethe_graphscollectioninthecurrentdatabase.
Note:thismethodisnotavailableinacluster.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/collection/products1/rename<<EOF
{
"name":"newname"
}
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products1/rename
{
"code":200,
"error":false,
"status":3,
"name":"newname",
"type":2,
"globallyUniqueId":"h68719E5AC6E7/10453",
"isSystem":false,
"id":"10453"
}
ReturnCodes
400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/collection/products1/rename<<EOF
{
"name":"newname"
}
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products1/rename
showresponsebody
Rotatejournalofacollection
rotatesthejournalofacollection
PUT/_api/collection/{collection-name}/rotate
PathParameters
collection-name(required):Thenameofthecollection.
Modifying
46
Rotatesthejournalofacollection.Thecurrentjournalofthecollectionwillbeclosedandmadearead-onlydatafile.Thepurposeoftherotatemethodistomakethedatainthefileavailableforcompaction(compactionisonlyperformedforread-onlydatafiles,andnotforjournals).
Savingnewdatainthecollectionsubsequentlywillcreateanewjournalfileautomaticallyifthereisnocurrentjournal.
Itreturnsanobjectwiththeattributes
result:willbetrueifrotationsucceeded
Note:thismethodisspecificfortheMMFilesstorageengine,andthereitisnotavailableinacluster.
Example:Rotatingthejournal:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/collection/products/rotate<<EOF
{
}
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/rotate
{
"code":200,
"error":false,
"result":true
}
Example:Rotatingifnojournalexists:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/collection/products/rotate<<EOF
{
}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"nojournal",
"code":400,
"errorNum":1105
}
ReturnCodes
400:Ifthecollectioncurrentlyhasnojournal,HTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Rotatingthejournal:
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/collection/products/rotate<<EOF
{
Modifying
47
}
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
location:/_api/collection/products/rotate
showresponsebodyRotatingifnojournalexists:
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/collection/products/rotate<<EOF
{
}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Modifying
48
HTTPInterfaceforDocumentsInthischapterwedescribetheRESTAPIofArangoDBfordocuments.
BasicapproachDetailedAPIdescription
Documents
49
BasicsandTerminology
Documents,Keys,HandlesandRevisions
DocumentsinArangoDBareJSONobjects.Theseobjectscanbenested(toanydepth)andmaycontainlists.Eachdocumenthasauniqueprimarykeywhichidentifiesitwithinitscollection.Furthermore,eachdocumentisuniquelyidentifiedbyitsdocumenthandleacrossallcollectionsinthesamedatabase.Differentrevisionsofthesamedocument(identifiedbyitshandle)canbedistinguishedbytheirdocumentrevision.Anytransactiononlyeverseesasinglerevisionofadocument.
Hereisanexampledocument:
{
"_id":"myusers/3456789",
"_key":"3456789",
"_rev":"14253647",
"firstName":"John",
"lastName":"Doe",
"address":{
"street":"RoadToNowhere1",
"city":"Gotham"
},
"hobbies":[
{name:"swimming",howFavorite:10},
{name:"biking",howFavorite:6},
{name:"programming",howFavorite:4}
]
}
Alldocumentscontainspecialattributes:thedocumenthandleisstoredasastringin_id,thedocument'sprimarykeyin_keyandthedocumentrevisionin_rev.Thevalueofthe_keyattributecanbespecifiedbytheuserwhencreatingadocument._idand_keyvaluesareimmutableoncethedocumenthasbeencreated.The_revvalueismaintainedbyArangoDBautomatically.
DocumentHandle
Adocumenthandleuniquelyidentifiesadocumentinthedatabase.Itisastringandconsistsofthecollection'snameandthedocumentkey(_keyattribute)separatedby/.
DocumentKey
Adocumentkeyuniquelyidentifiesadocumentinthecollectionitisstoredin.Itcanandshouldbeusedbyclientswhenspecificdocumentsarequeried.Thedocumentkeyisstoredinthe_keyattributeofeachdocument.ThekeyvaluesareautomaticallyindexedbyArangoDBinacollection'sprimaryindex.Thuslookingupadocumentbyitskeyisafastoperation.The_keyvalueofadocumentisimmutableoncethedocumenthasbeencreated.Bydefault,ArangoDBwillauto-generateadocumentkeyifno_keyattributeisspecified,andusetheuser-specified_keyotherwise.
Thisbehaviorcanbechangedonaper-collectionlevelbycreatingcollectionswiththekeyOptionsattribute.
UsingkeyOptionsitispossibletodisallowuser-specifiedkeyscompletely,ortoforceaspecificregimeforauto-generatingthe_keyvalues.
DocumentRevision
AsArangoDBsupportsMVCC(MultipleVersionConcurrencyControl),documentscanexistinmorethanonerevision.ThedocumentrevisionistheMVCCtokenusedtospecifyaparticularrevisionofadocument(identifiedbyits_id).Itisastringvaluecurrentlycontaininganintegernumberandisuniquewithinthelistofdocumentrevisionsforasingledocument.Documentrevisionscanbeusedtoconditionallyquery,update,replaceordeletedocumentsinthedatabase.Inordertofindaparticularrevisionofadocument,youneedthedocumenthandleorkey,andthedocumentrevision.
BasicsandTerminology
50
ArangoDBuses64bitunsignedintegervaluestomaintaindocumentrevisionsinternally.Whenreturningdocumentrevisionstoclients,ArangoDBwillputthemintoastringtoensuretherevisionisnotclippedbyclientsthatdonotsupportbigintegers.ClientsshouldtreattherevisionreturnedbyArangoDBasanopaquestringwhentheystoreoruseitlocally.ThiswillallowArangoDBtochangetheformatofrevisionslaterifthisshouldberequired.Clientscanuserevisionstoperformsimpleequality/non-equalitycomparisons(e.g.tocheckwhetheradocumenthaschangedornot),buttheyshouldnotuserevisionidstoperformgreater/lessthancomparisonswiththemtocheckifadocumentrevisionisolderthanoneanother,evenifthismightworkforsomecases.
DocumentEtag
ArangoDBtriestoadheretotheexistingHTTPstandardasfaraspossible.Tothisend,resultsofsingledocumentquerieshavetheHTTPheaderEtagsettothedocumentrevisionenclosedindoublequotes.
Thebasicoperations(create,read,exists,replace,update,delete)fordocumentsaremappedtothestandardHTTPmethods(POST,GET,HEAD,PUT,PATCHandDELETE).
Ifyoumodifyadocument,youcanusetheIf-Matchfieldtodetectconflicts.TherevisionofadocumentcanbecheckingusingtheHTTPmethodHEAD.
MultipleDocumentsinasingleRequest
BeginningwithArangoDB3.0thebasicdocumentAPIhasbeenextendedtohandlenotonlysingledocumentsbutmultipledocumentsinasinglerequest.Thisiscrucialforperformance,inparticularintheclustersituation,inwhichasinglerequestcaninvolvemultiplenetworkhopswithinthecluster.AnotheradvantageisthatitreducestheoverheadoftheHTTPprotocolandindividualnetworkroundtripsbetweentheclientandtheserver.ThegeneralideatoperformmultipledocumentoperationsinasinglerequestistouseaJSONarrayofobjectsintheplaceofasingledocument.Asaconsequence,documentkeys,handlesandrevisionsforpreconditionshavetobesuppliedembeddedintheindividualdocumentsgiven.Multipledocumentoperationsarerestrictedtoasingledocumentoredgecollections.SeetheAPIdescriptionsfordetails.
NotethattheGET,HEADandDELETEHTTPoperationsgenerallydonotallowtopassamessagebody.Thus,theycannotbeusedtoperformmultipledocumentoperationsinonerequest.However,thereareotherendpointstorequestanddeletemultipledocumentsinonerequest.FIXME:ADDSENSIBLELINKSHERE.
URIofaDocument
AnydocumentcanberetrievedusingitsuniqueURI:
http://server:port/_api/document/<document-handle>
Forexample,assumingthatthedocumenthandleisdemo/362549736,thentheURLofthatdocumentis:
http://localhost:8529/_api/document/demo/362549736
TheaboveURLschemadoesnotspecifyadatabasenameexplicitly,sothedefaultdatabase_systemwillbeused.Toexplicitlyspecifythedatabasecontext,usethefollowingURLschema:
http://server:port/_db/<database-name>/_api/document/<document-handle>
Example:
http://localhost:8529/_db/mydb/_api/document/demo/362549736
Note:ThefollowingexamplesusetheshortURLformatforbrevity.
Thedocumentrevisionisreturnedinthe"Etag"HTTPheaderwhenrequestingadocument.
IfyouobtainadocumentusingGETandyouwanttocheckwhetheranewerrevisionisavailable,thenyoucanusetheIf-None-Matchheader.Ifthedocumentisunchanged,aHTTP412(preconditionfailed)errorisreturned.
BasicsandTerminology
51
Ifyouwanttoquery,replace,updateordeleteadocument,thenyoucanusetheIf-Matchheader.Ifthedocumenthaschanged,thentheoperationisabortedandanHTTP412errorisreturned.
BasicsandTerminology
52
WorkingwithDocumentsusingREST
Readdocument
readsasingledocument
GET/_api/document/{document-handle}
PathParameters
document-handle(required):Thehandleofthedocument.
HeaderParameters
If-None-Match(optional):Ifthe"If-None-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasadifferentrevisionthanthegivenEtag.OtherwiseanHTTP304isreturned.If-Match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.
Returnsthedocumentidentifiedbydocument-handle.Thereturneddocumentcontainsthreespecialattributes:_idcontainingthedocumenthandle,_keycontainingkeywhichuniquelyidentifiesadocumentinagivencollectionand_revcontainingtherevision.
Example:Useadocumenthandle:
shell>curl--dump-http://localhost:8529/_api/document/products/11042
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YXa--_"
{
"_key":"11042",
"_id":"products/11042",
"_rev":"_WQ47YXa--_",
"hello":"world"
}
Example:UseadocumenthandleandanEtag:
shell>curl--header'If-None-Match:"_WQ47Yc2--_"'--dump-http://localhost:8529/_api/document/products/11118
Example:Unknowndocumenthandle:
shell>curl--dump-http://localhost:8529/_api/document/products/unknownhandle
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
WorkingwithDocuments
53
"errorMessage":"collectionnotfound:products",
"code":404,
"errorNum":1203
}
ReturnCodes
200:isreturnedifthedocumentwasfound304:isreturnedifthe"If-None-Match"headerisgivenandthedocumenthasthesameversion404:isreturnedifthedocumentorcollectionwasnotfound412:isreturnedifan"If-Match"headerisgivenandthefounddocumenthasadifferentversion.Theresponsewillalsocontainthefounddocument'scurrentrevisioninthe_revattribute.Additionally,theattributes_idand_keywillbereturned.
Examples
Useadocumenthandle:
shell>curl--dump-http://localhost:8529/_api/document/products/11042
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YXa--_"
showresponsebodyUseadocumenthandleandanEtag:
shell>curl--header'If-None-Match:"_WQ47Yc2--_"'--dump-
http://localhost:8529/_api/document/products/11118
Unknowndocumenthandle:
shell>curl--dump-http://localhost:8529/_api/document/products/unknownhandle
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Changesin3.0from2.8:
Therevqueryparameterhasbeenwithdrawn.ThesameeffectcanbeachievedwiththeIf-MatchHTTPheader.
Readdocumentheader
readsasingledocumenthead
HEAD/_api/document/{document-handle}
PathParameters
document-handle(required):Thehandleofthedocument.
HeaderParameters
If-None-Match(optional):Ifthe"If-None-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Ifthecurrentdocument
WorkingwithDocuments
54
revisionisnotequaltothespecifiedEtag,anHTTP200responseisreturned.Ifthecurrentdocumentrevisionisidenticaltothe
specifiedEtag,thenanHTTP304isreturned.If-Match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.
LikeGET,butonlyreturnstheheaderfieldsandnotthebody.Youcanusethiscalltogetthecurrentrevisionofadocumentorcheckifthedocumentwasdeleted.
Example:
shell>curl-XHEAD--dump-http://localhost:8529/_api/document/products/11102
ReturnCodes
200:isreturnedifthedocumentwasfound304:isreturnedifthe"If-None-Match"headerisgivenandthedocumenthasthesameversion404:isreturnedifthedocumentorcollectionwasnotfound412:isreturnedifan"If-Match"headerisgivenandthefounddocumenthasadifferentversion.Theresponsewillalsocontainthefounddocument'scurrentrevisionintheEtagheader.
Examples
shell>curl-XHEAD--dump-http://localhost:8529/_api/document/products/11102
Changesin3.0from2.8:
Therevqueryparameterhasbeenwithdrawn.ThesameeffectcanbeachievedwiththeIf-MatchHTTPheader.
Readalldocuments
readsalldocumentsfromcollection
PUT/_api/simple/all-keys
QueryParameters
AJSONobjectwiththesepropertiesisrequired:
type:Thetypeoftheresult.Thefollowingvaluesareallowed:id:returnsanarrayofdocumentids(_idattributes)key:returnsanarrayofdocumentkeys(_keyattributes)path:returnsanarrayofdocumentURIpaths.Thisisthedefault.
collection:Thenameofthecollection.Thisisonlyforbackwardcompatibility.InArangoDBversions<3.0,theURLpathwas/_api/documentandthiswaspassedinviathequeryparameter"collection".Thiscombinationwasremoved.
Returnsanarrayofallkeys,ids,orURIpathsforalldocumentsinthecollectionidentifiedbycollection.Thetypeoftheresultarrayisdeterminedbythetypeattribute.
Notethattheresultshavenodefinedorderandthustheordershouldnotbereliedon.
Example:Returnalldocumentpaths
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all-keys<<EOF
{
"collection":"products"
WorkingwithDocuments
55
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
"/_db/_system/_api/document/products/11084",
"/_db/_system/_api/document/products/11087",
"/_db/_system/_api/document/products/11080"
],
"hasMore":false,
"cached":false,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":3,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.000125885009765625
},
"warnings":[]
},
"error":false,
"code":201
}
Example:Returnalldocumentkeys
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all-keys<<EOF
{
"collection":"products",
"type":"id"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
"products/11062",
"products/11065",
"products/11058"
],
"hasMore":false,
"cached":false,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":3,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.00013065338134765625
},
"warnings":[]
},
"error":false,
"code":201
}
WorkingwithDocuments
56
Example:Collectiondoesnotexist
shell>curl--dump-http://localhost:8529/_api/document/doesnotexist
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"expectingGET/_api/document/<document-handle>",
"code":404,
"errorNum":1203
}
ReturnCodes
201:Allwentwell.404:Thecollectiondoesnotexist.
Examples
Returnalldocumentpaths
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all-keys
<<EOF
{
"collection":"products"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyReturnalldocumentkeys
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all-keys
<<EOF
{
"collection":"products",
"type":"id"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyCollectiondoesnotexist
shell>curl--dump-http://localhost:8529/_api/document/doesnotexist
WorkingwithDocuments
57
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Changesin3.0from2.8:
ThecollectionnameshouldnowbespecifiedintheURLpath.TheoldwaywiththeURLpath/_api/documentandtherequiredqueryparametercollectionstillworks.
Createdocument
createsdocuments
POST/_api/document/{collection}
PathParameters
collection(required):Thecollectioninwhichthecollectionistobecreated.
RequestBody(required)
AJSONrepresentationofasingledocumentorofanarrayofdocuments.
QueryParameters
collection(optional):Thenameofthecollection.Thisisonlyforbackwardcompatibility.InArangoDBversions<3.0,theURLpathwas/_api/documentandthisqueryparameterwasrequired.Thiscombinationstillworks,buttherecommendedwayistospecifythecollectionintheURLpath.waitForSync(optional):Waituntildocumenthasbeensyncedtodisk.returnNew(optional):Additionallyreturnthecompletenewdocumentundertheattributenewintheresult.silent(optional):Ifsettotrue,anemptyobjectwillbereturnedasresponse.Nometa-datawillbereturnedforthecreateddocument.Thisoptioncanbeusedtosavesomenetworktraffic.
Createsanewdocumentfromthedocumentgiveninthebody,unlessthereisalreadyadocumentwiththe_keygiven.Ifno_keyisgiven,anewunique_keyisgeneratedautomatically.
Thebodycanbeanarrayofdocuments,inwhichcasealldocumentsinthearrayareinsertedwiththesamesemanticsasforasingledocument.TheresultbodywillcontainaJSONarrayofthesamelengthastheinputarray,andeachentrycontainstheresultoftheoperationforthecorrespondinginput.IncaseofanerrortheentryisadocumentwithattributeserrorsettotrueanderrorCodesettotheerrorcodethathashappened.
Possiblygiven_idand_revattributesinthebodyarealwaysignored,theURLpartorthequeryparametercollectionrespectivelycounts.
Ifthedocumentwascreatedsuccessfully,thentheLocationheadercontainsthepathtothenewlycreateddocument.TheEtagheaderfieldcontainstherevisionofthedocument.Bothareonlysetinthesingledocumentcase.
Ifsilentisnotsettotrue,thebodyoftheresponsecontainsaJSONobject(singledocumentcase)withthefollowingattributes:
_idcontainsthedocumenthandleofthenewlycreateddocument_keycontainsthedocumentkey_revcontainsthedocumentrevision
Inthemulticasethebodyisanarrayofsuchobjects.
IfthecollectionparameterwaitForSyncisfalse,thenthecallreturnsassoonasthedocumenthasbeenaccepted.Itwillnotwaituntilthedocumentshavebeensyncedtodisk.
Optionally,thequeryparameterwaitForSynccanbeusedtoforcesynchronizationofthedocumentcreationoperationtodiskevenincasethatthewaitForSyncflaghadbeendisabledfortheentirecollection.Thus,thewaitForSyncqueryparametercanbeusedtoforcesynchronizationofjustthisspecificoperations.Tousethis,setthewaitForSyncparametertotrue.IfthewaitForSyncparameterisnot
WorkingwithDocuments
58
specifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.
IfthequeryparameterreturnNewistrue,then,foreachgenerateddocument,thecompletenewdocumentisreturnedunderthenewattributeintheresult.
Example:Createadocumentinacollectionnamedproducts.Notethattherevisionidentifiermightormightnotbyequaltotheauto-generatedkey.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products<<EOF
{"Hello":"World"}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YT6--_"
location:/_db/_system/_api/document/products/10976
{
"_id":"products/10976",
"_key":"10976",
"_rev":"_WQ47YT6--_"
}
Example:Createadocumentinacollectionnamedproductswithacollection-levelwaitForSyncvalueoffalse.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products<<EOF
{"Hello":"World"}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YRm--_"
location:/_db/_system/_api/document/products/10950
{
"_id":"products/10950",
"_key":"10950",
"_rev":"_WQ47YRm--_"
}
Example:Createadocumentinacollectionwithacollection-levelwaitForSyncvalueoffalse,butusingthewaitForSyncqueryparameter.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products?waitForSync=true<<EOF
{"Hello":"World"}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YW6--_"
location:/_db/_system/_api/document/products/11027
{
"_id":"products/11027",
"_key":"11027",
"_rev":"_WQ47YW6--_"
WorkingwithDocuments
59
}
Example:Unknowncollectionname
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products<<EOF
{"Hello":"World"}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"collectionnotfound:products",
"code":404,
"errorNum":1203
}
Example:Illegaldocument
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products<<EOF
{1:"World"}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"VPackErrorerror:Expecting'\"'or'}'",
"code":400,
"errorNum":600
}
Example:Insertmultipledocuments:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products<<EOF
[{"Hello":"Earth"},{"Hello":"Venus"},{"Hello":"Mars"}]
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"_id":"products/10991",
"_key":"10991",
"_rev":"_WQ47YUa--_"
},
{
"_id":"products/10995",
"_key":"10995",
"_rev":"_WQ47YUa--B"
},
{
WorkingwithDocuments
60
"_id":"products/10997",
"_key":"10997",
"_rev":"_WQ47YUa--D"
}
]
Example:UseofreturnNew:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products?returnNew=true<<EOF
{"Hello":"World"}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YU2--_"
location:/_db/_system/_api/document/products/11012
{
"_id":"products/11012",
"_key":"11012",
"_rev":"_WQ47YU2--_",
"new":{
"_key":"11012",
"_id":"products/11012",
"_rev":"_WQ47YU2--_",
"Hello":"World"
}
}
ReturnCodes
201:isreturnedifthedocumentswerecreatedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentswerecreatedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofonedocumentoranarrayofdocuments.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.409:isreturnedinthesingledocumentcaseifadocumentwiththesamequalifiersinanindexedattributeconflictswithanalreadyexistingdocumentandthusviolatesthatuniqueconstraint.Theresponsebodycontainsanerrordocumentinthiscase.Inthearraycaseonly201or202isreturned,butifanerroroccurred,theadditionalHTTPheaderX-Arango-Error-Codesisset,whichcontainsamapoftheerrorcodesthatoccurredtogetherwiththeirmultiplicities,asin:1205:10,1210:17whichmeansthatin10casestheerror1205"illegaldocumenthandle"andin17casestheerror1210"uniqueconstraintviolated"hashappened.
Examples
Createadocumentinacollectionnamedproducts.Notethattherevisionidentifiermightormightnotbyequaltotheauto-generatedkey.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products
<<EOF
{"Hello":"World"}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YT6--_"
location:/_db/_system/_api/document/products/10976
showresponsebody
WorkingwithDocuments
61
Createadocumentinacollectionnamedproductswithacollection-levelwaitForSyncvalueoffalse.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products
<<EOF
{"Hello":"World"}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YRm--_"
location:/_db/_system/_api/document/products/10950
showresponsebodyCreateadocumentinacollectionwithacollection-levelwaitForSyncvalueoffalse,butusingthewaitForSyncqueryparameter.
shell>curl-XPOST--data-binary@---dump-
http://localhost:8529/_api/document/products?waitForSync=true<<EOF
{"Hello":"World"}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YW6--_"
location:/_db/_system/_api/document/products/11027
showresponsebodyUnknowncollectionname
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products
<<EOF
{"Hello":"World"}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyIllegaldocument
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products
<<EOF
{1:"World"}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
WorkingwithDocuments
62
showresponsebodyInsertmultipledocuments:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products
<<EOF
[{"Hello":"Earth"},{"Hello":"Venus"},{"Hello":"Mars"}]
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"_id":"products/10991",
"_key":"10991",
"_rev":"_WQ47YUa--_"
},
{
"_id":"products/10995",
"_key":"10995",
"_rev":"_WQ47YUa--B"
},
{
"_id":"products/10997",
"_key":"10997",
"_rev":"_WQ47YUa--D"
}
]
UseofreturnNew:
shell>curl-XPOST--data-binary@---dump-
http://localhost:8529/_api/document/products?returnNew=true<<EOF
{"Hello":"World"}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YU2--_"
location:/_db/_system/_api/document/products/11012
showresponsebody
Changesin3.0from2.8:
ThecollectionnameshouldnowbespecifiedintheURLpath.TheoldwaywiththeURLpath/_api/documentandtherequiredqueryparametercollectionstillworks.ThepossibilitytoinsertmultipledocumentswithoneoperationisnewandthequeryparameterreturnNewhasbeenadded.
Replacedocument
replacesadocument
WorkingwithDocuments
63
PUT/_api/document/{document-handle}
RequestBody(required)
AJSONrepresentationofasingledocument.
PathParameters
document-handle(required):ThisURLparametermustbeadocumenthandle.
QueryParameters
waitForSync(optional):Waituntildocumenthasbeensyncedtodisk.ignoreRevs(optional):Bydefault,orifthisissettotrue,the_revattributesinthegivendocumentisignored.Ifthisissettofalse,thenthe_revattributegiveninthebodydocumentistakenasaprecondition.Thedocumentisonlyreplacedifthecurrentrevisionistheonespecified.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentundertheattributeoldintheresult.returnNew(optional):Returnadditionallythecompletenewdocumentundertheattributenewintheresult.silent(optional):Ifsettotrue,anemptyobjectwillbereturnedasresponse.Nometa-datawillbereturnedforthereplaceddocument.Thisoptioncanbeusedtosavesomenetworktraffic.
HeaderParameters
If-Match(optional):Youcanconditionallyreplaceadocumentbasedonatargetrevisionidbyusingtheif-matchHTTPheader.
Replacesthedocumentwithhandlewiththeoneinthebody,providedthereissuchadocumentandnopreconditionisviolated.
IftheIf-Matchheaderisspecifiedandtherevisionofthedocumentinthedatabaseisunequaltothegivenrevision,thepreconditionisviolated.
IfIf-MatchisnotgivenandignoreRevsisfalseandthereisa_revattributeinthebodyanditsvaluedoesnotmatchtherevisionofthedocumentinthedatabase,thepreconditionisviolated.
Ifapreconditionisviolated,anHTTP412isreturned.
Ifthedocumentexistsandcanbeupdated,thenanHTTP201oranHTTP202isreturned(dependingonwaitForSync,seebelow),theEtagheaderfieldcontainsthenewrevisionofthedocumentandtheLocationheadercontainsacompleteURLunderwhichthedocumentcanbequeried.
Optionally,thequeryparameterwaitForSynccanbeusedtoforcesynchronizationofthedocumentreplacementoperationtodiskevenincasethatthewaitForSyncflaghadbeendisabledfortheentirecollection.Thus,thewaitForSyncqueryparametercanbeusedtoforcesynchronizationofjustspecificoperations.Tousethis,setthewaitForSyncparametertotrue.IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.
Ifsilentisnotsettotrue,thebodyoftheresponsecontainsaJSONobjectwiththeinformationaboutthehandleandtherevision.Theattribute_idcontainstheknowndocument-handleoftheupdateddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthenewdocumentrevision.
IfthequeryparameterreturnOldistrue,thenthecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.
IfthequeryparameterreturnNewistrue,thenthecompletenewdocumentisreturnedunderthenewattributeintheresult.
Ifthedocumentdoesnotexist,thenaHTTP404isreturnedandthebodyoftheresponsecontainsanerrordocument.
Example:Usingadocumenthandle
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/document/products/11134<<EOF
{"Hello":"you"}
EOF
WorkingwithDocuments
64
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47Yd6--A"
location:/_db/_system/_api/document/products/11134
{
"_id":"products/11134",
"_key":"11134",
"_rev":"_WQ47Yd6--A",
"_oldRev":"_WQ47Yd6---"
}
Example:Unknowndocumenthandle
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/document/products/11170<<EOF
{}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"documentnotfound",
"code":404,
"errorNum":1202
}
Example:Producearevisionconflict
shell>curl-XPUT--header'If-Match:"_WQ47YfG--B"'--data-binary@---dump-http://localhost:8529/_api/document/products/11
151<<EOF
{"other":"content"}
EOF
HTTP/1.1412PreconditionFailed
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YfG--_"
{
"error":true,
"code":412,
"errorNum":1200,
"errorMessage":"preconditionfailed",
"_id":"products/11151",
"_key":"11151",
"_rev":"_WQ47YfG--_"
}
ReturnCodes
201:isreturnedifthedocumentwasreplacedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentwasreplacedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofadocument.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionorthedocumentwasnotfound.412:isreturnedifthepreconditionwasviolated.Theresponsewillalsocontainthefounddocuments'currentrevisionsinthe_revattributes.Additionally,theattributes_idand_keywillbereturned.
WorkingwithDocuments
65
Examples
Usingadocumenthandle
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/document/products/11134<<EOF
{"Hello":"you"}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47Yd6--A"
location:/_db/_system/_api/document/products/11134
showresponsebodyUnknowndocumenthandle
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/document/products/11170<<EOF
{}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyProducearevisionconflict
shell>curl-XPUT--header'If-Match:"_WQ47YfG--B"'--data-binary@---dump-
http://localhost:8529/_api/document/products/11151<<EOF
{"other":"content"}
EOF
HTTP/1.1412PreconditionFailed
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YfG--_"
showresponsebody
Changesin3.0from2.8:
TherearequitesomechangesinthisincomparisontoVersion2.8,butfewbreakexistingusage:
therevqueryparameterisgone(wasduplicationofIf-Match)thepolicyqueryparameterisgone(wasnon-sensical)theignoreRevsqueryparameterisnew,thedefaulttruegivesthetraditionalbehaviorasin2.8thereturnNewandreturnOldqueryparametersarenew
Thereshouldbeveryfewchangestobehaviorhappeninginreal-worldsituationsordrivers.Essentially,onehastoreplaceusageoftherevqueryparameterbyusageoftheIf-Matchheader.Thenon-sensicalcombinationofIf-Matchgivenandpolicy=lastnolongerworks,butcaneasilybeachievedbyleavingouttheIf-Matchheader.
WorkingwithDocuments
66
ThecollectionnameshouldnowbespecifiedintheURLpath.TheoldwaywiththeURLpath/_api/documentandtherequiredqueryparametercollectionstillworks.
Replacedocuments
replacesmultipledocuments
PUT/_api/document/{collection}
RequestBody(required)
AJSONrepresentationofanarrayofdocuments.
PathParameters
collection(required):ThisURLparameteristhenameofthecollectioninwhichthedocumentsarereplaced.
QueryParameters
waitForSync(optional):Waituntilthenewdocumentshavebeensyncedtodisk.ignoreRevs(optional):Bydefault,orifthisissettotrue,the_revattributesinthegivendocumentsareignored.Ifthisissettofalse,thenany_revattributegiveninabodydocumentistakenasaprecondition.Thedocumentisonlyreplacedifthecurrentrevisionistheonespecified.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentsundertheattributeoldintheresult.returnNew(optional):Returnadditionallythecompletenewdocumentsundertheattributenewintheresult.
Replacesmultipledocumentsinthespecifiedcollectionwiththeonesinthebody,thereplaceddocumentsarespecifiedbythe_keyattributesinthebodydocuments.
IfignoreRevsisfalseandthereisa_revattributeinadocumentinthebodyanditsvaluedoesnotmatchtherevisionofthecorrespondingdocumentinthedatabase,thepreconditionisviolated.
Ifthedocumentexistsandcanbeupdated,thenanHTTP201oranHTTP202isreturned(dependingonwaitForSync,seebelow).
Optionally,thequeryparameterwaitForSynccanbeusedtoforcesynchronizationofthedocumentreplacementoperationtodiskevenincasethatthewaitForSyncflaghadbeendisabledfortheentirecollection.Thus,thewaitForSyncqueryparametercanbeusedtoforcesynchronizationofjustspecificoperations.Tousethis,setthewaitForSyncparametertotrue.IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.
ThebodyoftheresponsecontainsaJSONarrayofthesamelengthastheinputarraywiththeinformationaboutthehandleandtherevisionofthereplaceddocuments.Ineachentry,theattribute_idcontainstheknowndocument-handleofeachupdateddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthenewdocumentrevision.Incaseofanerrororviolatedprecondition,anerrorobjectwiththeattributeerrorsettotrueandtheattributeerrorCodesettotheerrorcodeisbuilt.
IfthequeryparameterreturnOldistrue,then,foreachgenerateddocument,thecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.
IfthequeryparameterreturnNewistrue,then,foreachgenerateddocument,thecompletenewdocumentisreturnedunderthenewattributeintheresult.
Notethatifanypreconditionisviolatedoranerroroccurredwithsomeofthedocuments,thereturncodeisstill201or202,buttheadditionalHTTPheaderX-Arango-Error-Codesisset,whichcontainsamapoftheerrorcodesthatoccurredtogetherwiththeirmultiplicities,asin:1200:17,1205:10whichmeansthatin17casestheerror1200"revisionconflict"andin10casestheerror1205"illegaldocumenthandle"hashappened.
ReturnCodes
201:isreturnedifthedocumentswerereplacedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentswerereplacedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofanarrayofdocuments.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionwasnotfound.
WorkingwithDocuments
67
Changesin3.0from2.8:
Themultidocumentversionisnewin3.0.
Updatedocument
updatesadocument
PATCH/_api/document/{document-handle}
RequestBody(required)
AJSONrepresentationofadocumentupdateasanobject.
PathParameters
document-handle(required):ThisURLparametermustbeadocumenthandle.
QueryParameters
keepNull(optional):Iftheintentionistodeleteexistingattributeswiththepatchcommand,theURLqueryparameterkeepNullcanbeusedwithavalueoffalse.Thiswillmodifythebehaviorofthepatchcommandtoremoveanyattributesfromtheexistingdocumentthatarecontainedinthepatchdocumentwithanattributevalueofnull.mergeObjects(optional):Controlswhetherobjects(notarrays)willbemergedifpresentinboththeexistingandthepatchdocument.Ifsettofalse,thevalueinthepatchdocumentwilloverwritetheexistingdocument'svalue.Ifsettotrue,objectswillbemerged.Thedefaultistrue.waitForSync(optional):Waituntildocumenthasbeensyncedtodisk.ignoreRevs(optional):Bydefault,orifthisissettotrue,the_revattributesinthegivendocumentisignored.Ifthisissettofalse,thenthe_revattributegiveninthebodydocumentistakenasaprecondition.Thedocumentisonlyupdatedifthecurrentrevisionistheonespecified.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentundertheattributeoldintheresult.returnNew(optional):Returnadditionallythecompletenewdocumentundertheattributenewintheresult.silent(optional):Ifsettotrue,anemptyobjectwillbereturnedasresponse.Nometa-datawillbereturnedfortheupdateddocument.Thisoptioncanbeusedtosavesomenetworktraffic.
HeaderParameters
If-Match(optional):Youcanconditionallyupdateadocumentbasedonatargetrevisionidbyusingtheif-matchHTTPheader.
Partiallyupdatesthedocumentidentifiedbydocument-handle.ThebodyoftherequestmustcontainaJSONdocumentwiththeattributestopatch(thepatchdocument).Allattributesfromthepatchdocumentwillbeaddedtotheexistingdocumentiftheydonotyetexist,andoverwrittenintheexistingdocumentiftheydoexistthere.
Settinganattributevaluetonullinthepatchdocumentwillcauseavalueofnulltobesavedfortheattributebydefault.
IftheIf-Matchheaderisspecifiedandtherevisionofthedocumentinthedatabaseisunequaltothegivenrevision,thepreconditionisviolated.
IfIf-MatchisnotgivenandignoreRevsisfalseandthereisa_revattributeinthebodyanditsvaluedoesnotmatchtherevisionofthedocumentinthedatabase,thepreconditionisviolated.
Ifapreconditionisviolated,anHTTP412isreturned.
Ifthedocumentexistsandcanbeupdated,thenanHTTP201oranHTTP202isreturned(dependingonwaitForSync,seebelow),theEtagheaderfieldcontainsthenewrevisionofthedocument(indoublequotes)andtheLocationheadercontainsacompleteURLunderwhichthedocumentcanbequeried.
Optionally,thequeryparameterwaitForSynccanbeusedtoforcesynchronizationoftheupdateddocumentoperationtodiskevenincasethatthewaitForSyncflaghadbeendisabledfortheentirecollection.Thus,thewaitForSyncqueryparametercanbeusedtoforcesynchronizationofjustspecificoperations.Tousethis,setthewaitForSyncparametertotrue.IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.
WorkingwithDocuments
68
Ifsilentisnotsettotrue,thebodyoftheresponsecontainsaJSONobjectwiththeinformationaboutthehandleandtherevision.Theattribute_idcontainstheknowndocument-handleoftheupdateddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthenewdocumentrevision.
IfthequeryparameterreturnOldistrue,thenthecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.
IfthequeryparameterreturnNewistrue,thenthecompletenewdocumentisreturnedunderthenewattributeintheresult.
Ifthedocumentdoesnotexist,thenaHTTP404isreturnedandthebodyoftheresponsecontainsanerrordocument.
Example:Patchesanexistingdocumentwithnewcontent.
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10905<<EOF
{
"hello":"world"
}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YN6--B"
location:/_db/_system/_api/document/products/10905
{
"_id":"products/10905",
"_key":"10905",
"_rev":"_WQ47YN6--B",
"_oldRev":"_WQ47YN6--_"
}
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10905<<EOF
{
"numbers":{
"one":1,
"two":2,
"three":3,
"empty":null
}
}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YO---_"
location:/_db/_system/_api/document/products/10905
{
"_id":"products/10905",
"_key":"10905",
"_rev":"_WQ47YO---_",
"_oldRev":"_WQ47YN6--B"
}
shell>curl--dump-http://localhost:8529/_api/document/products/10905
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YO---_"
{
"_key":"10905",
"_id":"products/10905",
"_rev":"_WQ47YO---_",
"one":"world",
"hello":"world",
"numbers":{
"one":1,
WorkingwithDocuments
69
"two":2,
"three":3,
"empty":null
}
}
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10905?keepNull=false<<EOF
{
"hello":null,
"numbers":{
"four":4
}
}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YOG--_"
location:/_db/_system/_api/document/products/10905
{
"_id":"products/10905",
"_key":"10905",
"_rev":"_WQ47YOG--_",
"_oldRev":"_WQ47YO---_"
}
shell>curl--dump-http://localhost:8529/_api/document/products/10905
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YOG--_"
{
"_key":"10905",
"_id":"products/10905",
"_rev":"_WQ47YOG--_",
"one":"world",
"numbers":{
"empty":null,
"one":1,
"three":3,
"two":2,
"four":4
}
}
Example:MergingattributesofanobjectusingmergeObjects:
shell>curl--dump-http://localhost:8529/_api/document/products/10928
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YPK--_"
{
"_key":"10928",
"_id":"products/10928",
"_rev":"_WQ47YPK--_",
"inhabitants":{
"china":1366980000,
"india":1263590000,
"usa":319220000
}
}
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10928?mergeObjects=true<<EOF
{
"inhabitants":{
"indonesia":252164800,
WorkingwithDocuments
70
"brazil":203553000
}
}
EOF
shell>curl--dump-http://localhost:8529/_api/document/products/10928
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YPS---"
{
"_key":"10928",
"_id":"products/10928",
"_rev":"_WQ47YPS---",
"inhabitants":{
"china":1366980000,
"india":1263590000,
"usa":319220000,
"indonesia":252164800,
"brazil":203553000
}
}
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10928?mergeObjects=false<<EOF
{
"inhabitants":{
"pakistan":188346000
}
}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YPa--_"
location:/_db/_system/_api/document/products/10928
{
"_id":"products/10928",
"_key":"10928",
"_rev":"_WQ47YPa--_",
"_oldRev":"_WQ47YPS---"
}
shell>curl--dump-http://localhost:8529/_api/document/products/10928
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YPa--_"
{
"_key":"10928",
"_id":"products/10928",
"_rev":"_WQ47YPa--_",
"inhabitants":{
"pakistan":188346000
}
}
ReturnCodes
201:isreturnedifthedocumentwasupdatedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentwasupdatedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofadocument.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionorthedocumentwasnotfound.412:isreturnedifthepreconditionwasviolated.Theresponsewillalsocontainthefounddocuments'currentrevisionsinthe_revattributes.Additionally,theattributes_idand_keywillbereturned.
Examples
Patchesanexistingdocumentwithnewcontent.
WorkingwithDocuments
71
shell>curl-XPATCH--data-binary@---dump-
http://localhost:8529/_api/document/products/10905<<EOF
{
"hello":"world"
}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YN6--B"
location:/_db/_system/_api/document/products/10905
showresponsebodyMergingattributesofanobjectusingmergeObjects:
shell>curl--dump-http://localhost:8529/_api/document/products/10928
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YPK--_"
showresponsebody
Changesin3.0from2.8:
TherearequitesomechangesinthisincomparisontoVersion2.8,butfewbreakexistingusage:
therevqueryparameterisgone(wasduplicationofIf-Match)thepolicyqueryparameterisgone(wasnon-sensical)theignoreRevsqueryparameterisnew,thedefaulttruegivesthetraditionalbehaviorasin2.8thereturnNewandreturnOldqueryparametersarenew
Thereshouldbeveryfewchangestobehaviorhappeninginreal-worldsituationsordrivers.Essentially,onehastoreplaceusageoftherevqueryparameterbyusageoftheIf-Matchheader.Thenon-sensicalcombinationofIf-Matchgivenandpolicy=lastnolongerworks,butcaneasilybeachievedbyleavingouttheIf-Matchheader.
ThecollectionnameshouldnowbespecifiedintheURLpath.TheoldwaywiththeURLpath/_api/documentandtherequiredqueryparametercollectionstillworks.
Updatedocuments
updatesmultipledocuments
PATCH/_api/document/{collection}
RequestBody(required)
AJSONrepresentationofanarrayofdocumentupdatesasobjects.
PathParameters
collection(required):ThisURLparameteristhenameofthecollectioninwhichthedocumentsareupdated.
QueryParameters
keepNull(optional):Iftheintentionistodeleteexistingattributeswiththepatchcommand,theURLqueryparameterkeepNullcan
WorkingwithDocuments
72
beusedwithavalueoffalse.Thiswillmodifythebehaviorofthepatchcommandtoremoveanyattributesfromtheexistingdocumentthatarecontainedinthepatchdocumentwithanattributevalueofnull.mergeObjects(optional):Controlswhetherobjects(notarrays)willbemergedifpresentinboththeexistingandthepatchdocument.Ifsettofalse,thevalueinthepatchdocumentwilloverwritetheexistingdocument'svalue.Ifsettotrue,objectswillbemerged.Thedefaultistrue.waitForSync(optional):Waituntilthenewdocumentshavebeensyncedtodisk.ignoreRevs(optional):Bydefault,orifthisissettotrue,the_revattributesinthegivendocumentsareignored.Ifthisissettofalse,thenany_revattributegiveninabodydocumentistakenasaprecondition.Thedocumentisonlyupdatedifthecurrentrevisionistheonespecified.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentsundertheattributeoldintheresult.returnNew(optional):Returnadditionallythecompletenewdocumentsundertheattributenewintheresult.
Partiallyupdatesdocuments,thedocumentstoupdatearespecifiedbythe_keyattributesinthebodyobjects.ThebodyoftherequestmustcontainaJSONarrayofdocumentupdateswiththeattributestopatch(thepatchdocuments).Allattributesfromthepatchdocumentswillbeaddedtotheexistingdocumentsiftheydonotyetexist,andoverwrittenintheexistingdocumentsiftheydoexistthere.
Settinganattributevaluetonullinthepatchdocumentswillcauseavalueofnulltobesavedfortheattributebydefault.
IfignoreRevsisfalseandthereisa_revattributeinadocumentinthebodyanditsvaluedoesnotmatchtherevisionofthecorrespondingdocumentinthedatabase,thepreconditionisviolated.
Ifthedocumentexistsandcanbeupdated,thenanHTTP201oranHTTP202isreturned(dependingonwaitForSync,seebelow).
Optionally,thequeryparameterwaitForSynccanbeusedtoforcesynchronizationofthedocumentreplacementoperationtodiskevenincasethatthewaitForSyncflaghadbeendisabledfortheentirecollection.Thus,thewaitForSyncqueryparametercanbeusedtoforcesynchronizationofjustspecificoperations.Tousethis,setthewaitForSyncparametertotrue.IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.
ThebodyoftheresponsecontainsaJSONarrayofthesamelengthastheinputarraywiththeinformationaboutthehandleandtherevisionoftheupdateddocuments.Ineachentry,theattribute_idcontainstheknowndocument-handleofeachupdateddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthenewdocumentrevision.Incaseofanerrororviolatedprecondition,anerrorobjectwiththeattributeerrorsettotrueandtheattributeerrorCodesettotheerrorcodeisbuilt.
IfthequeryparameterreturnOldistrue,then,foreachgenerateddocument,thecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.
IfthequeryparameterreturnNewistrue,then,foreachgenerateddocument,thecompletenewdocumentisreturnedunderthenewattributeintheresult.
Notethatifanypreconditionisviolatedoranerroroccurredwithsomeofthedocuments,thereturncodeisstill201or202,buttheadditionalHTTPheaderX-Arango-Error-Codesisset,whichcontainsamapoftheerrorcodesthatoccurredtogetherwiththeirmultiplicities,asin:1200:17,1205:10whichmeansthatin17casestheerror1200"revisionconflict"andin10casestheerror1205"illegaldocumenthandle"hashappened.
ReturnCodes
201:isreturnedifthedocumentswereupdatedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentswereupdatedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofanarrayofdocuments.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionwasnotfound.
Changesin3.0from2.8:
Themultidocumentversionisnewin3.0.
Removesadocument
WorkingwithDocuments
73
removesadocument
DELETE/_api/document/{document-handle}
PathParameters
document-handle(required):Removesthedocumentidentifiedbydocument-handle.
QueryParameters
waitForSync(optional):Waituntildeletionoperationhasbeensyncedtodisk.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentundertheattributeoldintheresult.silent(optional):Ifsettotrue,anemptyobjectwillbereturnedasresponse.Nometa-datawillbereturnedfortheremoveddocument.Thisoptioncanbeusedtosavesomenetworktraffic.
HeaderParameters
If-Match(optional):Youcanconditionallyremoveadocumentbasedonatargetrevisionidbyusingtheif-matchHTTPheader.
Ifsilentisnotsettotrue,thebodyoftheresponsecontainsaJSONobjectwiththeinformationaboutthehandleandtherevision.Theattribute_idcontainstheknowndocument-handleoftheremoveddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthedocumentrevision.
IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.
IfthequeryparameterreturnOldistrue,thenthecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.
Example:Usingdocumenthandle:
shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10788
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YCu--_"
location:/_db/_system/_api/document/products/10788
{
"_id":"products/10788",
"_key":"10788",
"_rev":"_WQ47YCu--_"
}
Example:Unknowndocumenthandle:
shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10860
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"documentnotfound",
"code":404,
"errorNum":1202
}
WorkingwithDocuments
74
Example:Revisionconflict:
shell>curl-XDELETE--header'If-Match:"_WQ47YEu--B"'--dump-http://localhost:8529/_api/document/products/10805
HTTP/1.1412PreconditionFailed
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YEu--_"
{
"error":true,
"code":412,
"errorNum":1200,
"errorMessage":"preconditionfailed",
"_id":"products/10805",
"_key":"10805",
"_rev":"_WQ47YEu--_"
}
ReturnCodes
200:isreturnedifthedocumentwasremovedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentwasremovedsuccessfullyandwaitForSyncwasfalse.404:isreturnedifthecollectionorthedocumentwasnotfound.Theresponsebodycontainsanerrordocumentinthiscase.412:isreturnedifa"If-Match"headerorrevisgivenandthefounddocumenthasadifferentversion.Theresponsewillalsocontainthefounddocument'scurrentrevisioninthe_revattribute.Additionally,theattributes_idand_keywillbereturned.
Examples
Usingdocumenthandle:
shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10788
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YCu--_"
location:/_db/_system/_api/document/products/10788
showresponsebodyUnknowndocumenthandle:
shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10860
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyRevisionconflict:
shell>curl-XDELETE--header'If-Match:"_WQ47YEu--B"'--dump-
http://localhost:8529/_api/document/products/10805
HTTP/1.1412PreconditionFailed
x-content-type-options:nosniff
WorkingwithDocuments
75
content-type:application/json;charset=utf-8
etag:"_WQ47YEu--_"
showresponsebody
Changesin3.0from2.8:
ThereareonlyveryfewchangesinthisincomparisontoVersion2.8:
therevqueryparameterisgone(wasduplicationofIf-Match)thepolicyqueryparameterisgone(wasnon-sensical)thereturnOldqueryparameterisnew
Thereshouldbeveryfewchangestobehaviorhappeninginreal-worldsituationsordrivers.Essentially,onehastoreplaceusageoftherevqueryparameterbyusageoftheIf-Matchheader.Thenon-sensicalcombinationofIf-Matchgivenandpolicy=lastnolongerworks,butcaneasilybeachievedbyleavingouttheIf-Matchheader.
Removesmultipledocuments
removesmultipledocument
DELETE/_api/document/{collection}
RequestBody(required)
AJSONarrayofstringsordocuments.
PathParameters
collection(required):Collectionfromwhichdocumentsareremoved.
QueryParameters
waitForSync(optional):Waituntildeletionoperationhasbeensyncedtodisk.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentundertheattributeoldintheresult.ignoreRevs(optional):Ifsettotrue,ignoreany_revattributeintheselectors.Norevisioncheckisperformed.
Thebodyoftherequestisanarrayconsistingofselectorsfordocuments.Aselectorcaneitherbeastringwithakeyorastringwithadocumenthandleoranobjectwitha_keyattribute.ThisAPIcallremovesallspecifieddocumentsfromcollection.Iftheselectorisanobjectandhasa_revattribute,itisapreconditionthattheactualrevisionoftheremoveddocumentinthecollectionisthespecifiedone.
Thebodyoftheresponseisanarrayofthesamelengthastheinputarray.Foreachinputselector,theoutputcontainsaJSONobjectwiththeinformationabouttheoutcomeoftheoperation.Ifnoerroroccurred,anobjectisbuiltinwhichtheattribute_idcontainstheknowndocument-handleoftheremoveddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthedocumentrevision.Incaseofanerror,anobjectwiththeattributeerrorsettotrueanderrorCodesettotheerrorcodeisbuilt.
IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.
IfthequeryparameterreturnOldistrue,thenthecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.
Notethatifanypreconditionisviolatedoranerroroccurredwithsomeofthedocuments,thereturncodeisstill200or202,buttheadditionalHTTPheaderX-Arango-Error-Codesisset,whichcontainsamapoftheerrorcodesthatoccurredtogetherwiththeirmultiplicities,asin:1200:17,1205:10whichmeansthatin17casestheerror1200"revisionconflict"andin10casestheerror1205"illegaldocumenthandle"hashappened.
Example:
WorkingwithDocuments
76
Usingdocumenthandle:
shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10843
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YHa--_"
location:/_db/_system/_api/document/products/10843
{
"_id":"products/10843",
"_key":"10843",
"_rev":"_WQ47YHa--_"
}
Example:Unknowndocumenthandle:
shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10887
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"documentnotfound",
"code":404,
"errorNum":1202
}
Example:Revisionconflict:
shell>curl-XDELETE--header'If-Match:"_WQ47YFO--_"'--dump-http://localhost:8529/_api/document/products/10824
HTTP/1.1412PreconditionFailed
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YFK--_"
{
"error":true,
"code":412,
"errorNum":1200,
"errorMessage":"preconditionfailed",
"_id":"products/10824",
"_key":"10824",
"_rev":"_WQ47YFK--_"
}
ReturnCodes
200:isreturnedifwaitForSyncwastrue.202:isreturnedifwaitForSyncwasfalse.404:isreturnedifthecollectionwasnotfound.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Usingdocumenthandle:
shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10843
WorkingwithDocuments
77
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
etag:"_WQ47YHa--_"
location:/_db/_system/_api/document/products/10843
showresponsebodyUnknowndocumenthandle:
shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10887
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyRevisionconflict:
shell>curl-XDELETE--header'If-Match:"_WQ47YFO--_"'--dump-
http://localhost:8529/_api/document/products/10824
HTTP/1.1412PreconditionFailed
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:"_WQ47YFK--_"
showresponsebody
Changesin3.0from2.8:
Thisvariantisnewin3.0.NotethatitrequiresabodyintheDELETErequest.
WorkingwithDocuments
78
HTTPInterfaceforEdgesThisisanintroductiontoArangoDB'sRESTinterfaceforedges.
ArangoDBoffersgraphfunctionality;Edgesareonepartofthat.
Edges
79
AddressandEtagofanEdgeAlldocumentsinArangoDBhaveadocumenthandle.Thishandleuniquelyidentifiesadocument.AnydocumentcanberetrievedusingitsuniqueURI:
http://server:port/_api/document/<document-handle>
Edgesareaspecialvariationofdocuments.ToaccessanedgeusethesameURLformatasforadocument:
http://server:port/_api/document/<document-handle>
Forexample,assumedthatthedocumenthandle,whichisstoredinthe_idattributeoftheedge,isdemo/362549736,thentheURLofthatedgeis:
http://localhost:8529/_api/document/demo/362549736
TheaboveURLschemedoesnotspecifyadatabasenameexplicitly,sothedefaultdatabasewillbeused.Toexplicitlyspecifythedatabasecontext,usethefollowingURLschema:
http://server:port/_db/<database-name>/_api/document/<document-handle>
Example:
http://localhost:8529/_db/mydb/_api/document/demo/362549736
Note:thatthefollowingexamplesusetheshortURLformatforbrevity.
AddressandEtag
80
WorkingwithEdgesusingRESTThisisdocumentationtoArangoDB'sRESTinterfaceforedges.
Edgesaredocumentswithtwoadditionalattributes:_fromand_to.Theseattributesaremandatoryandmustcontainthedocument-handleofthefromandtoverticesofanedge.
UsethegeneraldocumentRESTapiforcreate/read/update/delete.
Readin-oroutboundedges
getedges
GET/_api/edges/{collection-id}
PathParameters
collection-id(required):Theidofthecollection.
QueryParameters
vertex(required):Theidofthestartvertex.direction(optional):Selectsinoroutdirectionforedges.Ifnotset,anyedgesarereturned.
Returnsanarrayofedgesstartingorendinginthevertexidentifiedbyvertex-handle.
Example:Anydirection
shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"edges":[
{
"_key":"6",
"_id":"edges/6",
"_from":"vertices/2",
"_to":"vertices/1",
"_rev":"_WQ47Ygy---",
"$label":"v2->v1"
},
{
"_key":"7",
"_id":"edges/7",
"_from":"vertices/4",
"_to":"vertices/1",
"_rev":"_WQ47Ygy--A",
"$label":"v4->v1"
},
{
"_key":"5",
"_id":"edges/5",
"_from":"vertices/1",
"_to":"vertices/3",
"_rev":"_WQ47Ygu--H",
"$label":"v1->v3"
}
],
"error":false,
"code":200,
"stats":{
"scannedIndex":3,
WorkingwithEdges
81
"filtered":0
}
}
Example:Inedges
shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=in
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"edges":[
{
"_key":"6",
"_id":"edges/6",
"_from":"vertices/2",
"_to":"vertices/1",
"_rev":"_WQ47Yj---_",
"$label":"v2->v1"
},
{
"_key":"7",
"_id":"edges/7",
"_from":"vertices/4",
"_to":"vertices/1",
"_rev":"_WQ47Yj---B",
"$label":"v4->v1"
}
],
"error":false,
"code":200,
"stats":{
"scannedIndex":2,
"filtered":0
}
}
Example:Outedges
shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=out
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"edges":[
{
"_key":"5",
"_id":"edges/5",
"_from":"vertices/1",
"_to":"vertices/3",
"_rev":"_WQ47Yjy--H",
"$label":"v1->v3"
}
],
"error":false,
"code":200,
"stats":{
"scannedIndex":1,
"filtered":0
}
WorkingwithEdges
82
}
ReturnCodes
200:isreturnediftheedgecollectionwasfoundandedgeswereretrieved.400:isreturnediftherequestcontainsinvalidparameters.404:isreturnediftheedgecollectionwasnotfound.
Examples
Anydirection
shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyInedges
shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=in
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyOutedges
shell>curl--dump-http://localhost:8529/_api/edges/edges?
vertex=vertices/1&direction=out
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
WorkingwithEdges
83
GeneralGraphsThischapterdescribestheRESTinterfaceforthemulti-collectiongraphmodule.Itallowsyoutodefineagraphthatisspreadacrossseveraledgeanddocumentcollections.Thereisnoneedtoincludethereferencedcollectionswithinthequery,thismodulewillhandleitforyou.
GeneralGraph
84
ManageyourgraphsThegraphmoduleprovidesfunctionsdealingwithgraphstructures.ExampleswillexplaintheRESTAPIonthesocialgraph:
Listallgraphs
Listsallgraphsknowntothegraphmodule.
GET/_api/gharial
Listsallgraphnamesstoredinthisdatabase.
Example:
shell>curl--dump-http://localhost:8529/_api/gharial
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"graphs":[
{
"_key":"routeplanner",
"_id":"_graphs/routeplanner",
"_rev":"_WQ47RH2--_",
"orphanCollections":[],
"edgeDefinitions":[
{
"collection":"germanHighway",
"from":[
"germanCity"
],
"to":[
"germanCity"
]
},
{
"collection":"frenchHighway",
"from":[
"frenchCity"
],
"to":[
"frenchCity"
]
},
{
"collection":"internationalHighway",
"from":[
"frenchCity",
"germanCity"
],
"to":[
"frenchCity",
"germanCity"
]
}
],
"numberOfShards":1,
"replicationFactor":1
},
{
"_key":"social",
"_id":"_graphs/social",
"_rev":"_WQ47Q8C--_",
Management
85
"orphanCollections":[],
"edgeDefinitions":[
{
"collection":"relation",
"from":[
"female",
"male"
],
"to":[
"female",
"male"
]
}
],
"numberOfShards":1,
"replicationFactor":1
}
],
"code":200
}
ReturnCodes
200:Isreturnedifthemoduleisavailableandthegraphscouldbelisted.
Examples
shell>curl--dump-http://localhost:8529/_api/gharial
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Createagraph
Createanewgraphinthegraphmodule.
POST/_api/gharial
Thecreationofagraphrequiresthenameofthegraphandadefinitionofitsedges.Seealsoedgedefinitions.
AJSONobjectwiththesepropertiesisrequired:
orphanCollections:Anarrayofadditionalvertexcollections.edgeDefinitions:Anarrayofdefinitionsfortheedgename:Nameofthegraph.isSmart:Defineifthecreatedgraphshouldbesmart.ThisonlyhaseffectinEnterpriseversion.options:
smartGraphAttribute:Theattributenamethatisusedtosmartlyshardtheverticesofagraph.EveryvertexinthisGraphhastohavethisattribute.Cannotbemodifiedlater.numberOfShards:Thenumberofshardsthatisusedforeverycollectionwithinthisgraph.Cannotbemodifiedlater.
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial<<EOF
{
"name":"myGraph",
"edgeDefinitions":[
{
"collection":"edges",
"from":[
"startVertices"
Management
86
],
"to":[
"endVertices"
]
}
]
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47OnC--_
{
"error":false,
"graph":{
"name":"myGraph",
"edgeDefinitions":[
{
"collection":"edges",
"from":[
"startVertices"
],
"to":[
"endVertices"
]
}
],
"orphanCollections":[],
"isSmart":false,
"numberOfShards":0,
"replicationFactor":1,
"smartGraphAttribute":"",
"_id":"_graphs/myGraph",
"_rev":"_WQ47OnC--_"
},
"code":202
}
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial<<EOF
{
"name":"myGraph",
"edgeDefinitions":[
{
"collection":"edges",
"from":[
"startVertices"
],
"to":[
"endVertices"
]
}
],
"isSmart":true,
"options":{
"numberOfShards":9,
"smartGraphAttribute":"region"
}
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47PHG--_
{
"error":false,
"graph":{
Management
87
"name":"myGraph",
"edgeDefinitions":[
{
"collection":"edges",
"from":[
"startVertices"
],
"to":[
"endVertices"
]
}
],
"orphanCollections":[],
"isSmart":false,
"numberOfShards":0,
"replicationFactor":1,
"smartGraphAttribute":"",
"_id":"_graphs/myGraph",
"_rev":"_WQ47PHG--_"
},
"code":202
}
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial<<EOF
{
"name":"myGraph",
"edgeDefinitions":[
{
"collection":"edges",
"from":[
"startVertices"
],
"to":[
"endVertices"
]
}
]
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47OnC--_
showresponsebody
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial<<EOF
{
"name":"myGraph",
"edgeDefinitions":[
{
"collection":"edges",
"from":[
"startVertices"
],
"to":[
"endVertices"
]
}
Management
88
],
"isSmart":true,
"options":{
"numberOfShards":9,
"smartGraphAttribute":"region"
}
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47PHG--_
showresponsebody
Getagraph
Getagraphfromthegraphmodule.
GET/_api/gharial/{graph-name}
Getsagraphfromthecollection_graphs.Returnsthedefinitioncontentofthisgraph.
Example:
shell>curl--dump-http://localhost:8529/_api/gharial/myGraph
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Qli--_
{
"error":false,
"graph":{
"name":"myGraph",
"edgeDefinitions":[
{
"collection":"edges",
"from":[
"startVertices"
],
"to":[
"endVertices"
]
}
],
"orphanCollections":[],
"isSmart":false,
"numberOfShards":1,
"replicationFactor":1,
"smartGraphAttribute":"",
"_id":"_graphs/myGraph",
"_rev":"_WQ47Qli--_"
},
"code":200
}
PathParameters
graph-name(required):Thenameofthegraph.
ReturnCodes
Management
89
200:Returnedifthegraphcouldbefound.404:Returnedifnographwiththisnamecouldbefound.
Examples
shell>curl--dump-http://localhost:8529/_api/gharial/myGraph
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Qli--_
showresponsebody
Dropagraph
deleteanexistinggraph
DELETE/_api/gharial/{graph-name}
Removesagraphfromthecollection_graphs.
Example:
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social?dropCollections=true
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"removed":true,
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.
QueryParameters
dropCollections(optional):Dropcollectionsofthisgraphaswell.Collectionswillonlybedroppediftheyarenotusedinothergraphs.
ReturnCodes
201:IsreturnedifthegraphcouldbedroppedandwaitForSyncisenabledforthe_graphscollection.202:ReturnedifthegraphcouldbedroppedandwaitForSyncisdisabledforthe_graphscollection.404:Returnedifnographwiththisnamecouldbefound.
Examples
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social?
dropCollections=true
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Management
90
showresponsebody
Listvertexcollections
Listsallvertexcollectionsusedinthisgraph.
GET/_api/gharial/{graph-name}/vertex
Listsallvertexcollectionswithinthisgraph.
Example:
shell>curl--dump-http://localhost:8529/_api/gharial/social/vertex
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"collections":[
"female",
"male"
],
"code":200
}
PathParameters
graph-name(required):Thenameofthegraph.
ReturnCodes
200:Isreturnedifthecollectionscouldbelisted.404:Returnedifnographwiththisnamecouldbefound.
Examples
shell>curl--dump-http://localhost:8529/_api/gharial/social/vertex
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Addvertexcollection
Addanadditionalvertexcollectiontothegraph.
POST/_api/gharial/{graph-name}/vertex
Addsavertexcollectiontothesetofcollectionsofthegraph.Ifthecollectiondoesnotexist,itwillbecreated.
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial/social/vertex<<EOF
{
"collection":"otherVertices"
}
EOF
Management
91
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47N8y--_
{
"error":false,
"graph":{
"name":"social",
"edgeDefinitions":[
{
"collection":"relation",
"from":[
"female",
"male"
],
"to":[
"female",
"male"
]
}
],
"orphanCollections":[
"otherVertices"
],
"isSmart":false,
"numberOfShards":1,
"replicationFactor":1,
"smartGraphAttribute":"",
"_id":"_graphs/social",
"_rev":"_WQ47N8y--_"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.
ReturnCodes
201:ReturnediftheedgecollectioncouldbeaddedsuccessfullyandwaitForSyncistrue.202:ReturnediftheedgecollectioncouldbeaddedsuccessfullyandwaitForSyncisfalse.404:Returnedifnographwiththisnamecouldbefound.
Examples
shell>curl-XPOST--data-binary@---dump-
http://localhost:8529/_api/gharial/social/vertex<<EOF
{
"collection":"otherVertices"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47N8y--_
showresponsebody
Removevertexcollection
Removeavertexcollectionformthegraph.
Management
92
DELETE/_api/gharial/{graph-name}/vertex/{collection-name}
Removesavertexcollectionfromthegraphandoptionallydeletesthecollection,ifitisnotusedinanyothergraph.
Example:Youcanremovevertexcollectionsthatarenotusedinanyedgecollection:
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/vertex/otherVertices
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47T_e--_
{
"error":false,
"graph":{
"name":"social",
"edgeDefinitions":[
{
"collection":"relation",
"from":[
"female",
"male"
],
"to":[
"female",
"male"
]
}
],
"orphanCollections":[],
"isSmart":false,
"numberOfShards":1,
"replicationFactor":1,
"smartGraphAttribute":"",
"_id":"_graphs/social",
"_rev":"_WQ47T_e--_"
},
"code":202
}
Example:Youcannotremovevertexcollectionsthatareusedinedgecollections:
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/vertex/male
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorNum":1928,
"errorMessage":"notinorphancollection",
"code":400
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollection.
QueryParameters
Management
93
dropCollection(optional):Dropthecollectionaswell.Collectionwillonlybedroppedifitisnotusedinothergraphs.
ReturnCodes
201:ReturnedifthevertexcollectionwasremovedfromthegraphsuccessfullyandwaitForSyncistrue.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.400:Returnedifthevertexcollectionisstillusedinanedgedefinition.Inthiscaseitcannotberemovedfromthegraphyet,ithastoberemovedfromtheedgedefinitionfirst.404:Returnedifnographwiththisnamecouldbefound.
Examples
Youcanremovevertexcollectionsthatarenotusedinanyedgecollection:
shell>curl-XDELETE--dump-
http://localhost:8529/_api/gharial/social/vertex/otherVertices
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47T_e--_
showresponsebodyYoucannotremovevertexcollectionsthatareusedinedgecollections:
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/vertex/male
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Listedgedefinitions
Listsalledgedefinitions
GET/_api/gharial/{graph-name}/edge
Listsalledgecollectionswithinthisgraph.
Example:
shell>curl--dump-http://localhost:8529/_api/gharial/social/edge
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"collections":[
"relation"
],
"code":200
}
PathParameters
Management
94
graph-name(required):Thenameofthegraph.
ReturnCodes
200:Isreturnediftheedgedefinitionscouldbelisted.404:Returnedifnographwiththisnamecouldbefound.
Examples
shell>curl--dump-http://localhost:8529/_api/gharial/social/edge
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Addedgedefinition
Addanewedgedefinitiontothegraph
POST/_api/gharial/{graph-name}/edge
Addsanadditionaledgedefinitiontothegraph.
Thisedgedefinitionhastocontainacollectionandanarrayofeachfromandtovertexcollections.Anedgedefinitioncanonlybeaddedifthisdefinitioniseithernotusedinanyothergraph,oritisusedwithexactlythesamedefinition.Itisnotpossibletostoreadefinition"e"from"v1"to"v2"intheonegraph,and"e"from"v2"to"v1"intheothergraph.
AJSONobjectwiththesepropertiesisrequired:
to(string):Oneormanyvertexcollectionsthatcancontaintargetvertices.from(string):Oneormanyvertexcollectionsthatcancontainsourcevertices.collection:Thenameoftheedgecollectiontobeused.
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge<<EOF
{
"collection":"works_in",
"from":[
"female",
"male"
],
"to":[
"city"
]
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Mr6--_
{
"error":false,
"graph":{
"name":"social",
"edgeDefinitions":[
{
"collection":"relation",
"from":[
"female",
"male"
Management
95
],
"to":[
"female",
"male"
]
},
{
"collection":"works_in",
"from":[
"female",
"male"
],
"to":[
"city"
]
}
],
"orphanCollections":[],
"isSmart":false,
"numberOfShards":1,
"replicationFactor":1,
"smartGraphAttribute":"",
"_id":"_graphs/social",
"_rev":"_WQ47Mr6--_"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.
ReturnCodes
201:ReturnedifthedefinitioncouldbeaddedsuccessfullyandwaitForSyncisenabledforthe_graphscollection.202:ReturnedifthedefinitioncouldbeaddedsuccessfullyandwaitForSyncisdisabledforthe_graphscollection.400:Returnedifthedefininitioncouldnotbeadded,theedgecollectionisusedinanothergraphwithadifferentsignature.404:Returnedifnographwiththisnamecouldbefound.
Examples
shell>curl-XPOST--data-binary@---dump-
http://localhost:8529/_api/gharial/social/edge<<EOF
{
"collection":"works_in",
"from":[
"female",
"male"
],
"to":[
"city"
]
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Mr6--_
showresponsebody
Replaceanedgedefinition
Management
96
Replaceanexistingedgedefinition
PUT/_api/gharial/{graph-name}/edge/{definition-name}
Changeonespecificedgedefinition.Thiswillmodifyalloccurrencesofthisdefinitioninallgraphsknowntoyourdatabase.
AJSONobjectwiththesepropertiesisrequired:
to(string):Oneormanyvertexcollectionsthatcancontaintargetvertices.from(string):Oneormanyvertexcollectionsthatcancontainsourcevertices.collection:Thenameoftheedgecollectiontobeused.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge/relation<<EOF
{
"collection":"relation",
"from":[
"female",
"male",
"animal"
],
"to":[
"female",
"male",
"animal"
]
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47TS6--_
{
"error":false,
"graph":{
"name":"social",
"edgeDefinitions":[
{
"collection":"relation",
"from":[
"animal",
"female",
"male"
],
"to":[
"animal",
"female",
"male"
]
}
],
"orphanCollections":[],
"isSmart":false,
"numberOfShards":1,
"replicationFactor":1,
"smartGraphAttribute":"",
"_id":"_graphs/social",
"_rev":"_WQ47TS6--_"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.definition-name(required):Thenameoftheedgecollectionusedinthedefinition.
ReturnCodes
Management
97
201:ReturnediftherequestwassuccessfulandwaitForSyncistrue.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.400:Returnedifnoedgedefinitionwiththisnameisfoundinthegraph.404:Returnedifnographwiththisnamecouldbefound.
Examples
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/gharial/social/edge/relation<<EOF
{
"collection":"relation",
"from":[
"female",
"male",
"animal"
],
"to":[
"female",
"male",
"animal"
]
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47TS6--_
showresponsebody
Removeanedgedefinitionfromthegraph
Removeanedgedefinitionformthegraph
DELETE/_api/gharial/{graph-name}/edge/{definition-name}
Removeoneedgedefinitionfromthegraph.Thiswillonlyremovetheedgecollection,thevertexcollectionsremainuntouchedandcanstillbeusedinyourqueries.
Example:
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/edge/relation
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47QNS--_
{
"error":false,
"graph":{
"name":"social",
"edgeDefinitions":[],
"orphanCollections":[
"female",
"male"
],
"isSmart":false,
"numberOfShards":1,
Management
98
"replicationFactor":1,
"smartGraphAttribute":"",
"_id":"_graphs/social",
"_rev":"_WQ47QNS--_"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.definition-name(required):Thenameoftheedgecollectionusedinthedefinition.
QueryParameters
dropCollection(optional):Dropthecollectionaswell.Collectionwillonlybedroppedifitisnotusedinothergraphs.
ReturnCodes
201:ReturnediftheedgedefinitioncouldberemovedfromthegraphandwaitForSyncistrue.202:ReturnediftheedgedefinitioncouldberemovedfromthegraphandwaitForSyncisfalse.400:Returnedifnoedgedefinitionwiththisnameisfoundinthegraph.404:Returnedifnographwiththisnamecouldbefound.
Examples
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/edge/relation
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47QNS--_
showresponsebody
Management
99
HandlingVerticesExampleswillexplaintheRESTAPItothegraphmoduleonthesocialgraph:
Createavertex
createanewvertex
POST/_api/gharial/{graph-name}/vertex/{collection-name}
Addsavertextothegivencollection.
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial/social/vertex/male<<EOF
{
"name":"Francis"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47NdC--_
{
"error":false,
"vertex":{
"_id":"male/8068",
"_key":"8068",
"_rev":"_WQ47NdC--_"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollectionthevertexbelongsto.
QueryParameters
waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.
RequestBody(required)
ThebodyhastobetheJSONobjecttobestored.
ReturnCodes
201:ReturnedifthevertexcouldbeaddedandwaitForSyncistrue.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographornovertexcollectionwiththisnamecouldbefound.
Examples
shell>curl-XPOST--data-binary@---dump-
http://localhost:8529/_api/gharial/social/vertex/male<<EOF
{
"name":"Francis"
}
Vertices
100
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47NdC--_
showresponsebody
Getavertex
fetchesanexistingvertex
GET/_api/gharial/{graph-name}/vertex/{collection-name}/{vertex-key}
Getsavertexfromthegivencollection.
Example:
shell>curl--dump-http://localhost:8529/_api/gharial/social/vertex/female/alice
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Qx6--_
{
"error":false,
"vertex":{
"_key":"alice",
"_id":"female/alice",
"_rev":"_WQ47Qx6--_",
"name":"Alice"
},
"code":200
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollectionthevertexbelongsto.vertex-key(required):The_keyattributeofthevertex.
HeaderParameters
if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.
ReturnCodes
200:Returnedifthevertexcouldbefound.404:Returnedifnographwiththisname,novertexcollectionornovertexwiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.
Examples
shell>curl--dump-http://localhost:8529/_api/gharial/social/vertex/female/alice
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
Vertices
101
etag:_WQ47Qx6--_
showresponsebody
Modifyavertex
replaceanexistingvertex
PATCH/_api/gharial/{graph-name}/vertex/{collection-name}/{vertex-key}
Updatesthedataofthespecificvertexinthecollection.
Example:
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/gharial/social/vertex/female/alice<<EOF
{
"age":26
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47SSm--_
{
"error":false,
"vertex":{
"_id":"female/alice",
"_key":"alice",
"_rev":"_WQ47SSm--_",
"_oldRev":"_WQ47SSa--B"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollectionthevertexbelongsto.vertex-key(required):The_keyattributeofthevertex.
QueryParameters
waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.keepNull(optional):Defineifvaluessettonullshouldbestored.Bydefaultthekeyisnotremovedfromthedocument.
HeaderParameters
if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisupdated,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.
RequestBody(required)
ThebodyhastocontainaJSONobjectcontainingexactlytheattributesthatshouldbereplaced.
ReturnCodes
200:Returnedifthevertexcouldbeupdated.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,novertexcollectionornovertexwiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.
Examples
Vertices
102
shell>curl-XPATCH--data-binary@---dump-
http://localhost:8529/_api/gharial/social/vertex/female/alice<<EOF
{
"age":26
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47SSm--_
showresponsebody
Replaceavertex
replacesanexistingvertex
PUT/_api/gharial/{graph-name}/vertex/{collection-name}/{vertex-key}
Replacesthedataofavertexinthecollection.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/gharial/social/vertex/female/alice<<EOF
{
"name":"AliceCooper",
"age":26
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47TpK--_
{
"error":false,
"vertex":{
"_id":"female/alice",
"_key":"alice",
"_rev":"_WQ47TpK--_",
"_oldRev":"_WQ47Toy--B"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollectionthevertexbelongsto.vertex-key(required):The_keyattributeofthevertex.
QueryParameters
waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.
HeaderParameters
if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisupdated,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.
Vertices
103
RequestBody(required)
ThebodyhastobetheJSONobjecttobestored.
ReturnCodes
200:Returnedifthevertexcouldbereplaced.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,novertexcollectionornovertexwiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.
Examples
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/gharial/social/vertex/female/alice<<EOF
{
"name":"AliceCooper",
"age":26
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47TpK--_
showresponsebody
Removeavertex
removesavertexfromagraph
DELETE/_api/gharial/{graph-name}/vertex/{collection-name}/{vertex-key}
Removesavertexfromthecollection.
Example:
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/vertex/female/alice
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"removed":true,
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollectionthevertexbelongsto.vertex-key(required):The_keyattributeofthevertex.
QueryParameters
waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.
HeaderParameters
Vertices
104
if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisupdated,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.
ReturnCodes
200:Returnedifthevertexcouldberemoved.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,novertexcollectionornovertexwiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.
Examples
shell>curl-XDELETE--dump-
http://localhost:8529/_api/gharial/social/vertex/female/alice
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Vertices
105
HandlingEdgesExampleswillexplaintheRESTAPIformanipulatingedgesofthegraphmoduleontheknowsgraph:
Createanedge
Createsanedgeinanexistinggraph
POST/_api/gharial/{graph-name}/edge/{collection-name}
Createsanewedgeinthecollection.Withinthebodythehastocontaina_fromand_tovaluereferencingtovalidverticesinthegraph.Furthermoretheedgehastobevalidinthedefinitionofthisedgecollection.
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge/relation<<EOF
{
"type":"friend",
"_from":"female/alice",
"_to":"female/diana"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Mfu--_
{
"error":false,
"edge":{
"_id":"relation/7889",
"_key":"7889",
"_rev":"_WQ47Mfu--_"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameoftheedgecollectiontheedgebelongsto.
QueryParameters
waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk._from(required):_to(required):
RequestBody(required)
ThebodyhastobetheJSONobjecttobestored.
ReturnCodes
201:Returnediftheedgecouldbecreated.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.
Examples
shell>curl-XPOST--data-binary@---dump-
Edges
106
http://localhost:8529/_api/gharial/social/edge/relation<<EOF
{
"type":"friend",
"_from":"female/alice",
"_to":"female/diana"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Mfu--_
showresponsebody
Getanedge
fetchanedge
GET/_api/gharial/{graph-name}/edge/{collection-name}/{edge-key}
Getsanedgefromthegivencollection.
Example:
shell>curl--dump-http://localhost:8529/_api/gharial/social/edge/relation/8613
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47QdC--D
{
"error":false,
"edge":{
"_key":"8613",
"_id":"relation/8613",
"_from":"female/alice",
"_to":"male/bob",
"_rev":"_WQ47QdC--D",
"type":"married",
"vertex":"alice"
},
"code":200
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameoftheedgecollectiontheedgebelongsto.edge-key(required):The_keyattributeofthevertex.
HeaderParameters
if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.
ReturnCodes
200:Returnediftheedgecouldbefound.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.
Edges
107
412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.
Examples
shell>curl--dump-http://localhost:8529/_api/gharial/social/edge/relation/8613
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47QdC--D
showresponsebodyExampleswillexplaintheAPIonthesocialgraph:
Modifyanedge
modifyanexistingedge
PATCH/_api/gharial/{graph-name}/edge/{collection-name}/{edge-key}
Updatesthedataofthespecificedgeinthecollection.
Example:
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge/relation/9263<<EOF
{
"since":"01.01.2001"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Sgy--_
{
"error":false,
"edge":{
"_id":"relation/9263",
"_key":"9263",
"_rev":"_WQ47Sgy--_",
"_oldRev":"_WQ47Sgm--H"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameoftheedgecollectiontheedgebelongsto.edge-key(required):The_keyattributeofthevertex.
QueryParameters
waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.keepNull(optional):Defineifvaluessettonullshouldbestored.Bydefaultthekeyisnotremovedfromthedocument.
RequestBody(required)
ThebodyhastobeaJSONobjectcontainingtheattributestobeupdated.
ReturnCodes
Edges
108
200:Returnediftheedgecouldbeupdated.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.
Examples
shell>curl-XPATCH--data-binary@---dump-
http://localhost:8529/_api/gharial/social/edge/relation/9263<<EOF
{
"since":"01.01.2001"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47Sgy--_
showresponsebody
Replaceanedge
replacethecontentofanexistingedge
PUT/_api/gharial/{graph-name}/edge/{collection-name}/{edge-key}
Replacesthedataofanedgeinthecollection.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge/relation/9340<<EOF
{
"type":"divorced",
"_from":"female/alice",
"_to":"male/bob"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47SvK--_
{
"error":false,
"edge":{
"_id":"relation/9340",
"_key":"9340",
"_rev":"_WQ47SvK--_",
"_oldRev":"_WQ47SvC--H"
},
"code":202
}
PathParameters
graph-name(required):Thenameofthegraph.collection-name(required):Thenameoftheedgecollectiontheedgebelongsto.edge-key(required):The_keyattributeofthevertex.
QueryParameters
Edges
109
waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.
HeaderParameters
if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisupdated,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.
RequestBody(required)
ThebodyhastobetheJSONobjecttobestored.
ReturnCodes
201:ReturnediftherequestwassuccessfulbutwaitForSyncistrue.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.
Examples
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/gharial/social/edge/relation/9340<<EOF
{
"type":"divorced",
"_from":"female/alice",
"_to":"male/bob"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
content-type:application/json;charset=utf-8
etag:_WQ47SvK--_
showresponsebody
Removeanedge
removesanedgefromgraph
DELETE/_api/gharial/{graph-name}/edge/{collection-name}/{edge-key}
Removesanedgefromthecollection.
Example:
shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/edge/relation/8310
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"removed":true,
"code":202
}
PathParameters
Edges
110
graph-name(required):Thenameofthegraph.collection-name(required):Thenameoftheedgecollectiontheedgebelongsto.edge-key(required):The_keyattributeofthevertex.
QueryParameters
waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.
HeaderParameters
if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisupdated,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.
ReturnCodes
200:Returnediftheedgecouldberemoved.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.
Examples
shell>curl-XDELETE--dump-
http://localhost:8529/_api/gharial/social/edge/relation/8310
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Edges
111
HTTPInterfaceforTraversals
Traversals
ArangoDB'sgraphtraversalsareexecutedontheserver.Traversalscanbeinitiatedbyclientsbysendingthetraversaldescriptionforexecutiontotheserver.
TraversalsinArangoDBareusedtowalkoveragraphstoredinoneedgecollection.Itcaneasilybedescribedwhichedgesofthegraphshouldbefollowedandwhichactionsshouldbeperformedoneachvisitedvertex.Furthermoretheorderingofvisitingthenodescanbespecified,forinstancedepth-firstorbreadth-firstsearchareoffered.
ExecutingTraversalsviaHTTP
executesatraversal
executeaserver-sidetraversal
POST/_api/traversal
Startsatraversalstartingfromagivenvertexandfollowing.edgescontainedinagivenedgeCollection.Therequestmustcontainthefollowingattributes.
AJSONobjectwiththesepropertiesisrequired:
sort:body(JavaScript)codeofacustomcomparisonfunctionfortheedges.Thesignatureofthisfunctionis(l,r)->integer(wherelandrareedges)andmustreturn-1iflissmallerthan,+1iflisgreaterthan,and0iflandrareequal.Thereasonforthisisthefollowing:Theorderofedgesreturnedforacertainvertexisundefined.Thisisbecausethereisnonaturalorderofedgesforavertexwithmultipleconnectededges.Toexplicitlydefinetheorderinwhichedgesonthevertexarefollowed,youcanspecifyanedgecomparatorfunctionwiththisattribute.NotethatthevalueherehastobeastringtoconformtotheJSONstandard,whichinturnisparsedasfunctionbodyontheserverside.Furthermorenotethatthisattributeisonlyusedforthestandardexpanders.Ifyouuseyourcustomexpanderyouhavetodothesortingyourselfwithintheexpandercode.direction:directionfortraversal
ifset,mustbeeither"outbound" ,"inbound" ,or"any"ifnotset,theexpanderattributemustbespecified
minDepth:ANDedwithanyexistingfilters):visitsonlynodesinatleastthegivendepthstartVertex:idofthestartVertex,e.g."users/foo" .visitor:body(JavaScript)codeofcustomvisitorfunctionfunctionsignature:(config,result,vertex,path,connected)->voidThevisitorfunctioncandoanything,butitsreturnvalueisignored.Topopulatearesult,usetheresultvariablebyreference.Notethattheconnectedargumentisonlypopulatedwhentheorderattributeissetto"preorder-expander" .itemOrder:itemiterationordercanbe"forward" or"backward"strategy:traversalstrategycanbe"depthfirst" or"breadthfirst"filter:defaultistoincludeallnodes:body(JavaScriptcode)ofcustomfilterfunctionfunctionsignature:(config,vertex,path)->mixedcanreturnfourdifferentstringvalues:
"exclude" ->thisvertexwillnotbevisited."prune" ->theedgesofthisvertexwillnotbefollowed."" orundefined->visitthevertexandfollowit'sedges.Array->containinganycombinationoftheabove.Ifthereisatleastone"exclude" or"prune" respectivlyiscontained,it'seffectwilloccur.
init:body(JavaScript)codeofcustomresultinitializationfunctionfunctionsignature:(config,result)->voidinitializeanyvaluesinresultwithwhatisrequiredmaxIterations:Maximumnumberofiterationsineachtraversal.Thisnumbercanbesettopreventendlessloopsintraversalofcyclicgraphs.WhenatraversalperformsasmanyiterationsasthemaxIterationsvalue,thetraversalwillabortwithanerror.IfmaxIterationsisnotset,aserver-definedvaluemaybeused.maxDepth:ANDedwithanyexistingfiltersvisitsonlynodesinatmostthegivendepthuniqueness:specifiesuniquenessforverticesandedgesvisited.Ifset,mustbeanobjectlikethis:"uniqueness":{"vertices":"none"|"global"|"path","edges":"none"|"global"|"path"}
Traversals
112
order:traversalordercanbe"preorder" ,"postorder" or"preorder-expander"graphName:nameofthegraphthatcontainstheedges.EitheredgeCollectionorgraphNamehastobegiven.IncasebothvaluesaresetthegraphNameisprefered.expander:body(JavaScript)codeofcustomexpanderfunctionmustbesetifdirectionattributeisnotsetfunctionsignature:(config,vertex,path)->arrayexpandermustreturnanarrayoftheconnectionsforvertexeachconnectionisanobjectwiththeattributesedgeandvertexedgeCollection:nameofthecollectionthatcontainstheedges.
IftheTraversalissuccessfullyexecutedHTTP200willbereturned.Additionallytheresultobjectwillbereturnedbythetraversal.
Forsuccessfultraversals,thereturnedJSONobjecthasthefollowingproperties:
error:booleanflagtoindicateifanerroroccurred(falseinthiscase)
code:theHTTPstatuscode
result:thereturnvalueofthetraversal
Ifthetraversalspecificationiseithermissingormalformed,theserverwillrespondwithHTTP400.
ThebodyoftheresponsewillthencontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:
error:booleanflagtoindicatethatanerroroccurred(trueinthiscase)
code:theHTTPstatuscode
errorNum:theservererrornumber
errorMessage:adescriptiveerrormessage
Example:InthefollowingexamplestheunderlyinggraphwillcontainfivepersonsAlice,Bob,Charlie,DaveandEve.Wewillhavethefollowingdirectedrelations:
AliceknowsBobBobknowsCharlieBobknowsDaveEveknowsAliceEveknowsBob
ThestartingvertexwillalwaysbeAlice.
Followonlyoutboundedges
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gHO--B",
"name":"Alice"
},
{
Traversals
113
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gHO--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gHO--F",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gHS--_",
"name":"Dave"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gHO--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"14017",
"_id":"knows/14017",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gHS--D",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gHO--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gHO--D",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"14017",
"_id":"knows/14017",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gHS--D",
"vertex":"alice"
},
{
"_key":"14021",
"_id":"knows/14021",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47gHS--F",
"vertex":"bob"
}
],
"vertices":[
Traversals
114
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gHO--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gHO--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gHO--F",
"name":"Charlie"
}
]
},
{
"edges":[
{
"_key":"14017",
"_id":"knows/14017",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gHS--D",
"vertex":"alice"
},
{
"_key":"14024",
"_id":"knows/14024",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47gHS--H",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gHO--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gHO--D",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gHS--_",
"name":"Dave"
}
]
}
]
}
},
"error":false,
"code":200
}
Example:Followonlyinboundedges
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
Traversals
115
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"inbound"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47g-K--_",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47g-K--H",
"name":"Eve"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47g-K--_",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13676",
"_id":"knows/13676",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47g-O--_",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47g-K--_",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47g-K--H",
"name":"Eve"
}
]
}
]
}
},
"error":false,
"code":200
}
Traversals
116
Example:Followanydirectionofedges
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"uniqueness":{
"vertices":"none",
"edges":"global"
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fuu--B",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fuu--D",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fuu--F",
"name":"Dave"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fuu--H",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
}
]
},
{
Traversals
117
"edges":[
{
"_key":"13099",
"_id":"knows/13099",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fuy--_",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fuu--B",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"13099",
"_id":"knows/13099",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fuy--_",
"vertex":"alice"
},
{
"_key":"13103",
"_id":"knows/13103",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47fuy--B",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fuu--B",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fuu--D",
"name":"Charlie"
}
]
},
{
"edges":[
{
"_key":"13099",
"_id":"knows/13099",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fuy--_",
"vertex":"alice"
},
{
Traversals
118
"_key":"13106",
"_id":"knows/13106",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47fuy--D",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fuu--B",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fuu--F",
"name":"Dave"
}
]
},
{
"edges":[
{
"_key":"13099",
"_id":"knows/13099",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fuy--_",
"vertex":"alice"
},
{
"_key":"13112",
"_id":"knows/13112",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fuy--H",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fuu--B",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fuu--H",
"name":"Eve"
}
]
},
{
"edges":[
{
"_key":"13099",
"_id":"knows/13099",
"_from":"persons/alice",
"_to":"persons/bob",
Traversals
119
"_rev":"_WQ47fuy--_",
"vertex":"alice"
},
{
"_key":"13112",
"_id":"knows/13112",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fuy--H",
"vertex":"eve"
},
{
"_key":"13109",
"_id":"knows/13109",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fuy--F",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fuu--B",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fuu--H",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fuu--_",
"name":"Alice"
}
]
}
]
}
},
"error":false,
"code":200
}
Example:ExcludingCharlieandBob
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"filter":"if(vertex.name===\"Bob\"||vertex.name===\"Charlie\"){return\"exclude\";}return;"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
Traversals
120
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f5W--_",
"name":"Alice"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47f5W--F",
"name":"Dave"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f5W--_",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13505",
"_id":"knows/13505",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47f5W--J",
"vertex":"alice"
},
{
"_key":"13512",
"_id":"knows/13512",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47f5a--B",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f5W--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f5W--B",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47f5W--F",
"name":"Dave"
}
]
}
]
}
},
"error":false,
"code":200
}
Traversals
121
Example:DonotfollowedgesfromBob
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"filter":"if(vertex.name===\"Bob\"){return\"prune\";}return;"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f7m--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f7m--D",
"name":"Bob"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f7m--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13588",
"_id":"knows/13588",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47f7q--_",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f7m--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f7m--D",
"name":"Bob"
}
]
}
]
}
Traversals
122
},
"error":false,
"code":200
}
Example:Visitonlynodesinadepthofatleast2
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"minDepth":2
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gF---D",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gF---F",
"name":"Dave"
}
],
"paths":[
{
"edges":[
{
"_key":"13934",
"_id":"knows/13934",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gF---J",
"vertex":"alice"
},
{
"_key":"13938",
"_id":"knows/13938",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47gF---L",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gF---_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gF---B",
"name":"Bob"
},
Traversals
123
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gF---D",
"name":"Charlie"
}
]
},
{
"edges":[
{
"_key":"13934",
"_id":"knows/13934",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gF---J",
"vertex":"alice"
},
{
"_key":"13941",
"_id":"knows/13941",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47gF---N",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gF---_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gF---B",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gF---F",
"name":"Dave"
}
]
}
]
}
},
"error":false,
"code":200
}
Example:Visitonlynodesinadepthofatmost1
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"maxDepth":1
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Traversals
124
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gAa--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gAa--B",
"name":"Bob"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gAa--_",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13745",
"_id":"knows/13745",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gAa--J",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gAa--_",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gAa--B",
"name":"Bob"
}
]
}
]
}
},
"error":false,
"code":200
}
Example:Usingavisitorfunctiontoreturnvertexidsonly
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"visitor":"result.visited.vertices.push(vertex._id);"
Traversals
125
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
"persons/alice",
"persons/bob",
"persons/charlie",
"persons/dave"
],
"paths":[]
}
},
"error":false,
"code":200
}
Example:Countallvisitednodesandreturnalistofnodesonly
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"init":"result.visited=0;result.myVertices=[];",
"visitor":"result.visited++;result.myVertices.push(vertex);"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":4,
"myVertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gMS--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gMS--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gMS--F",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gMS--H",
"name":"Dave"
}
]
},
"error":false,
Traversals
126
"code":200
}
Example:ExpandonlyinboundedgesofAliceandoutboundedgesofEve
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"expander":"varconnections=[];if(vertex.name===\"Alice\"){config.datasource.getInEdges(vertex).forEach(function(e)
{connections.push({vertex:require(\"internal\").db._document(e._from),edge:e});});}if(vertex.name===\"Eve\"){config.da
tasource.getOutEdges(vertex).forEach(function(e){connections.push({vertex:require(\"internal\").db._document(e._to),edge:e
});});}returnconnections;"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gOq--_",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gOq--H",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gOq--B",
"name":"Bob"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gOq--_",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"14302",
"_id":"knows/14302",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47gOq--P",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
Traversals
127
"_rev":"_WQ47gOq--_",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gOq--H",
"name":"Eve"
}
]
},
{
"edges":[
{
"_key":"14302",
"_id":"knows/14302",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47gOq--P",
"vertex":"eve"
},
{
"_key":"14305",
"_id":"knows/14305",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47gOu--_",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gOq--_",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gOq--H",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gOq--B",
"name":"Bob"
}
]
}
]
}
},
"error":false,
"code":200
}
Example:Followthedepthfirststrategy
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"strategy":"depthfirst"
}
EOF
HTTP/1.1200OK
Traversals
128
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fyS--F",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fyS--H",
"name":"Dave"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fyS--F",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fyS--H",
"name":"Dave"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
}
],
"paths":[
{
Traversals
129
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13302",
"_id":"knows/13302",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fyW--B",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"13302",
"_id":"knows/13302",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fyW--B",
"vertex":"alice"
},
{
"_key":"13306",
"_id":"knows/13306",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47fyW--D",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fyS--F",
"name":"Charlie"
}
]
},
Traversals
130
{
"edges":[
{
"_key":"13302",
"_id":"knows/13302",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fyW--B",
"vertex":"alice"
},
{
"_key":"13309",
"_id":"knows/13309",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47fyW--F",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fyS--H",
"name":"Dave"
}
]
},
{
"edges":[
{
"_key":"13302",
"_id":"knows/13302",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fyW--B",
"vertex":"alice"
},
{
"_key":"13315",
"_id":"knows/13315",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fyW--J",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
Traversals
131
"name":"Eve"
}
]
},
{
"edges":[
{
"_key":"13302",
"_id":"knows/13302",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fyW--B",
"vertex":"alice"
},
{
"_key":"13315",
"_id":"knows/13315",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fyW--J",
"vertex":"eve"
},
{
"_key":"13312",
"_id":"knows/13312",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fyW--H",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13312",
"_id":"knows/13312",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fyW--H",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
Traversals
132
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
"name":"Eve"
}
]
},
{
"edges":[
{
"_key":"13312",
"_id":"knows/13312",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fyW--H",
"vertex":"eve"
},
{
"_key":"13315",
"_id":"knows/13315",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fyW--J",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"13312",
"_id":"knows/13312",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fyW--H",
"vertex":"eve"
},
{
"_key":"13315",
"_id":"knows/13315",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fyW--J",
"vertex":"eve"
},
{
"_key":"13306",
"_id":"knows/13306",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47fyW--D",
"vertex":"bob"
}
],
"vertices":[
Traversals
133
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fyS--F",
"name":"Charlie"
}
]
},
{
"edges":[
{
"_key":"13312",
"_id":"knows/13312",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fyW--H",
"vertex":"eve"
},
{
"_key":"13315",
"_id":"knows/13315",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fyW--J",
"vertex":"eve"
},
{
"_key":"13309",
"_id":"knows/13309",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47fyW--F",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fyS--H",
Traversals
134
"name":"Dave"
}
]
},
{
"edges":[
{
"_key":"13312",
"_id":"knows/13312",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fyW--H",
"vertex":"eve"
},
{
"_key":"13315",
"_id":"knows/13315",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fyW--J",
"vertex":"eve"
},
{
"_key":"13302",
"_id":"knows/13302",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fyW--B",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fyW--_",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fyS--D",
"name":"Bob"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fyS--B",
"name":"Alice"
}
]
}
]
}
},
"error":false,
"code":200
}
Example:Usingpostorderordering
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
Traversals
135
"graphName":"knows_graph",
"direction":"any",
"order":"postorder"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gJa--F",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gJa--H",
"name":"Dave"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gJa--F",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gJa--H",
"name":"Dave"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
},
{
"_key":"alice",
Traversals
136
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
}
],
"paths":[
{
"edges":[
{
"_key":"14100",
"_id":"knows/14100",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gJa--L",
"vertex":"alice"
},
{
"_key":"14104",
"_id":"knows/14104",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47gJa--N",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gJa--F",
"name":"Charlie"
}
]
},
{
"edges":[
{
"_key":"14100",
"_id":"knows/14100",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gJa--L",
"vertex":"alice"
},
{
"_key":"14107",
"_id":"knows/14107",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47gJe--_",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
Traversals
137
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gJa--H",
"name":"Dave"
}
]
},
{
"edges":[
{
"_key":"14100",
"_id":"knows/14100",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gJa--L",
"vertex":"alice"
},
{
"_key":"14113",
"_id":"knows/14113",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47gJe--D",
"vertex":"eve"
},
{
"_key":"14110",
"_id":"knows/14110",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47gJe--B",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"14100",
"_id":"knows/14100",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gJa--L",
"vertex":"alice"
},
{
"_key":"14113",
Traversals
138
"_id":"knows/14113",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47gJe--D",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
}
]
},
{
"edges":[
{
"_key":"14100",
"_id":"knows/14100",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gJa--L",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"14110",
"_id":"knows/14110",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47gJe--B",
"vertex":"eve"
},
{
"_key":"14113",
"_id":"knows/14113",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47gJe--D",
"vertex":"eve"
},
{
"_key":"14104",
"_id":"knows/14104",
"_from":"persons/bob",
Traversals
139
"_to":"persons/charlie",
"_rev":"_WQ47gJa--N",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47gJa--F",
"name":"Charlie"
}
]
},
{
"edges":[
{
"_key":"14110",
"_id":"knows/14110",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47gJe--B",
"vertex":"eve"
},
{
"_key":"14113",
"_id":"knows/14113",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47gJe--D",
"vertex":"eve"
},
{
"_key":"14107",
"_id":"knows/14107",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47gJe--_",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
Traversals
140
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47gJa--H",
"name":"Dave"
}
]
},
{
"edges":[
{
"_key":"14110",
"_id":"knows/14110",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47gJe--B",
"vertex":"eve"
},
{
"_key":"14113",
"_id":"knows/14113",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47gJe--D",
"vertex":"eve"
},
{
"_key":"14100",
"_id":"knows/14100",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47gJa--L",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"14110",
"_id":"knows/14110",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47gJe--B",
"vertex":"eve"
},
{
"_key":"14113",
Traversals
141
"_id":"knows/14113",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47gJe--D",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47gJa--D",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"14110",
"_id":"knows/14110",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47gJe--B",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47gJa--J",
"name":"Eve"
}
]
},
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47gJa--B",
"name":"Alice"
}
]
}
]
}
},
"error":false,
"code":200
}
Example:
Traversals
142
Usingbackwarditem-ordering:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"itemOrder":"backward"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fwi--_",
"name":"Dave"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fwe--F",
"name":"Charlie"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"dave",
Traversals
143
"_id":"persons/dave",
"_rev":"_WQ47fwi--_",
"name":"Dave"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fwe--F",
"name":"Charlie"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13203",
"_id":"knows/13203",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fwi--J",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
}
]
},
{
"edges":[
{
"_key":"13203",
"_id":"knows/13203",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fwi--J",
"vertex":"eve"
},
{
"_key":"13206",
"_id":"knows/13206",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fwi--L",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
Traversals
144
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"13203",
"_id":"knows/13203",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fwi--J",
"vertex":"eve"
},
{
"_key":"13206",
"_id":"knows/13206",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fwi--L",
"vertex":"eve"
},
{
"_key":"13193",
"_id":"knows/13193",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fwi--D",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13203",
"_id":"knows/13203",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fwi--J",
"vertex":"eve"
Traversals
145
},
{
"_key":"13206",
"_id":"knows/13206",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fwi--L",
"vertex":"eve"
},
{
"_key":"13200",
"_id":"knows/13200",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47fwi--H",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fwi--_",
"name":"Dave"
}
]
},
{
"edges":[
{
"_key":"13203",
"_id":"knows/13203",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fwi--J",
"vertex":"eve"
},
{
"_key":"13206",
"_id":"knows/13206",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fwi--L",
"vertex":"eve"
},
{
"_key":"13197",
"_id":"knows/13197",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47fwi--F",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
Traversals
146
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fwe--F",
"name":"Charlie"
}
]
},
{
"edges":[
{
"_key":"13193",
"_id":"knows/13193",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fwi--D",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"13193",
"_id":"knows/13193",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fwi--D",
"vertex":"alice"
},
{
"_key":"13206",
"_id":"knows/13206",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fwi--L",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
Traversals
147
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
}
]
},
{
"edges":[
{
"_key":"13193",
"_id":"knows/13193",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fwi--D",
"vertex":"alice"
},
{
"_key":"13206",
"_id":"knows/13206",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47fwi--L",
"vertex":"eve"
},
{
"_key":"13203",
"_id":"knows/13203",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47fwi--J",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47fwi--B",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
}
]
},
{
"edges":[
{
"_key":"13193",
"_id":"knows/13193",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fwi--D",
"vertex":"alice"
Traversals
148
},
{
"_key":"13200",
"_id":"knows/13200",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47fwi--H",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47fwi--_",
"name":"Dave"
}
]
},
{
"edges":[
{
"_key":"13193",
"_id":"knows/13193",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47fwi--D",
"vertex":"alice"
},
{
"_key":"13197",
"_id":"knows/13197",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47fwi--F",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47fwe--B",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47fwe--D",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47fwe--F",
"name":"Charlie"
}
]
}
]
}
},
"error":false,
"code":200
Traversals
149
}
Example:Edgesshouldonlybeincludedonceglobally,butnodesareincludedeverytimetheyarevisited
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"uniqueness":{
"vertices":"none",
"edges":"global"
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":{
"visited":{
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f2q--C",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47f2q--E",
"name":"Charlie"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47f2q--G",
"name":"Dave"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47f2q--I",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
}
],
"paths":[
{
"edges":[],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
Traversals
150
}
]
},
{
"edges":[
{
"_key":"13411",
"_id":"knows/13411",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47f2q--K",
"vertex":"alice"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f2q--C",
"name":"Bob"
}
]
},
{
"edges":[
{
"_key":"13411",
"_id":"knows/13411",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47f2q--K",
"vertex":"alice"
},
{
"_key":"13415",
"_id":"knows/13415",
"_from":"persons/bob",
"_to":"persons/charlie",
"_rev":"_WQ47f2u--_",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f2q--C",
"name":"Bob"
},
{
"_key":"charlie",
"_id":"persons/charlie",
"_rev":"_WQ47f2q--E",
"name":"Charlie"
}
]
},
{
"edges":[
{
"_key":"13411",
"_id":"knows/13411",
"_from":"persons/alice",
"_to":"persons/bob",
Traversals
151
"_rev":"_WQ47f2q--K",
"vertex":"alice"
},
{
"_key":"13418",
"_id":"knows/13418",
"_from":"persons/bob",
"_to":"persons/dave",
"_rev":"_WQ47f2u--B",
"vertex":"bob"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f2q--C",
"name":"Bob"
},
{
"_key":"dave",
"_id":"persons/dave",
"_rev":"_WQ47f2q--G",
"name":"Dave"
}
]
},
{
"edges":[
{
"_key":"13411",
"_id":"knows/13411",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47f2q--K",
"vertex":"alice"
},
{
"_key":"13424",
"_id":"knows/13424",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47f2u--F",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f2q--C",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47f2q--I",
"name":"Eve"
}
]
},
{
"edges":[
{
Traversals
152
"_key":"13411",
"_id":"knows/13411",
"_from":"persons/alice",
"_to":"persons/bob",
"_rev":"_WQ47f2q--K",
"vertex":"alice"
},
{
"_key":"13424",
"_id":"knows/13424",
"_from":"persons/eve",
"_to":"persons/bob",
"_rev":"_WQ47f2u--F",
"vertex":"eve"
},
{
"_key":"13421",
"_id":"knows/13421",
"_from":"persons/eve",
"_to":"persons/alice",
"_rev":"_WQ47f2u--D",
"vertex":"eve"
}
],
"vertices":[
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
},
{
"_key":"bob",
"_id":"persons/bob",
"_rev":"_WQ47f2q--C",
"name":"Bob"
},
{
"_key":"eve",
"_id":"persons/eve",
"_rev":"_WQ47f2q--I",
"name":"Eve"
},
{
"_key":"alice",
"_id":"persons/alice",
"_rev":"_WQ47f2q--A",
"name":"Alice"
}
]
}
]
}
},
"error":false,
"code":200
}
Example:Iftheunderlyinggraphiscyclic,maxIterationsshouldbeset
TheunderlyinggraphhastwoverticesAliceandBob.Withthedirectededges:
AliceknowsBobBobknowsAlice
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
Traversals
153
"uniqueness":{
"vertices":"none",
"edges":"none"
},
"maxIterations":5
}
EOF
HTTP/1.1500InternalServerError
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"code":500,
"errorNum":1909,
"errorMessage":"toomanyiterations-tryincreasingthevalueof'maxIterations'"
}
ReturnCodes
200:IfthetraversalisfullyexecutedHTTP200willbereturned.400:Ifthetraversalspecificationiseithermissingormalformed,theserverwillrespondwithHTTP400.404:TheserverwillrespondedwithHTTP404ifthespecifiededgecollectiondoesnotexist,orthespecifiedstartvertexcannotbefound.500:TheserverwillrespondedwithHTTP500whenanerroroccursinsidethetraversalorifatraversalperformsmorethanmaxIterationsiterations.
Examples
InthefollowingexamplestheunderlyinggraphwillcontainfivepersonsAlice,Bob,Charlie,DaveandEve.Wewillhavethefollowingdirectedrelations:
AliceknowsBobBobknowsCharlieBobknowsDaveEveknowsAliceEveknowsBobThestartingvertexwillalwaysbeAlice.Followonlyoutboundedges
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyFollowonlyinboundedges
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"inbound"
}
EOF
Traversals
154
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyFollowanydirectionofedges
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"uniqueness":{
"vertices":"none",
"edges":"global"
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyExcludingCharlieandBob
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"filter":"if(vertex.name===\"Bob\"||vertex.name===\"Charlie\"){return
\"exclude\";}return;"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyDonotfollowedgesfromBob
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"filter":"if(vertex.name===\"Bob\"){return\"prune\";}return;"
}
EOF
Traversals
155
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyVisitonlynodesinadepthofatleast2
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"minDepth":2
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyVisitonlynodesinadepthofatmost1
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"maxDepth":1
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingavisitorfunctiontoreturnvertexidsonly
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"visitor":"result.visited.vertices.push(vertex._id);"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Traversals
156
showresponsebodyCountallvisitednodesandreturnalistofnodesonly
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"outbound",
"init":"result.visited=0;result.myVertices=[];",
"visitor":"result.visited++;result.myVertices.push(vertex);"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyExpandonlyinboundedgesofAliceandoutboundedgesofEve
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"expander":"varconnections=[];if(vertex.name===\"Alice\")
{config.datasource.getInEdges(vertex).forEach(function(e){connections.push({vertex:
require(\"internal\").db._document(e._from),edge:e});});}if(vertex.name===\"Eve\")
{config.datasource.getOutEdges(vertex).forEach(function(e){connections.push({vertex:
require(\"internal\").db._document(e._to),edge:e});});}returnconnections;"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyFollowthedepthfirststrategy
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"strategy":"depthfirst"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Traversals
157
showresponsebodyUsingpostorderordering
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"order":"postorder"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingbackwarditem-ordering:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"itemOrder":"backward"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyEdgesshouldonlybeincludedonceglobally,butnodesareincludedeverytimetheyarevisited
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"uniqueness":{
"vertices":"none",
"edges":"global"
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Traversals
158
showresponsebodyIftheunderlyinggraphiscyclic,maxIterationsshouldbesetTheunderlyinggraphhastwoverticesAliceandBob.Withthedirectededges:
AliceknowsBobBobknowsAlice
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF
{
"startVertex":"persons/alice",
"graphName":"knows_graph",
"direction":"any",
"uniqueness":{
"vertices":"none",
"edges":"none"
},
"maxIterations":5
}
EOF
HTTP/1.1500InternalServerError
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyAllexampleswereusingthisgraph:
Traversals
159
HTTPInterfaceforAQLQueryCursors
DatabaseCursors
ThisisanintroductiontoArangoDB'sHTTPInterfaceforQueries.ResultsofAQLandsimplequeriesarereturnedascursorsinordertobatchthecommunicationbetweenserverandclient.Eachcallreturnsanumberofdocumentsinabatchandanindicationifthecurrentbatchhasbeenthefinalbatch.Dependingonthequery,thetotalnumberofdocumentsintheresultsetmightormightnotbeknowninadvance.Inordertofreeserverresourcestheclientshoulddeletethecursorassoonasitisnolongerneeded.
Toexecuteaquery,thequerydetailsneedtobeshippedfromtheclienttotheserverviaanHTTPPOSTrequest.
AQLQueryCursors
160
RetrievingqueryresultsSelectqueriesareexecutedon-the-flyontheserverandtheresultsetwillbereturnedbacktotheclient.
Therearetwowaystheclientcangettheresultsetfromtheserver:
InasingleroundtripUsingacursor
Singleroundtrip
Theserverwillonlytransferacertainnumberofresultdocumentsbacktotheclientinoneroundtrip.ThisnumberiscontrollablebytheclientbysettingthebatchSizeattributewhenissuingthequery.
Ifthecompleteresultcanbetransferredtotheclientinonego,theclientdoesnotneedtoissueanyfurtherrequest.TheclientcancheckwhetherithasretrievedthecompleteresultsetbycheckingthehasMoreattributeoftheresultset.Ifitissettofalse,thentheclienthasfetchedthecompleteresultsetfromtheserver.Inthiscasenoserversidecursorwillbecreated.
>curl--data@--XPOST--dump-http://localhost:8529/_api/cursor
{"query":"FORuINusersLIMIT2RETURNu","count":true,"batchSize":2}
HTTP/1.1201Created
Content-type:application/json
{
"hasMore":false,
"error":false,
"result":[
{
"name":"user1",
"_rev":"210304551",
"_key":"210304551",
"_id":"users/210304551"
},
{
"name":"user2",
"_rev":"210304552",
"_key":"210304552",
"_id":"users/210304552"
}
],
"code":201,
"count":2
}
Usingacursor
Iftheresultsetcontainsmoredocumentsthanshouldbetransferredinasingleroundtrip(i.e.assetviathebatchSizeattribute),theserverwillreturnthefirstfewdocumentsandcreateatemporarycursor.Thecursoridentifierwillalsobereturnedtotheclient.Theserverwillputthecursoridentifierintheidattributeoftheresponseobject.Furthermore,thehasMoreattributeoftheresponseobjectwillbesettotrue.Thisisanindicationfortheclientthatthereareadditionalresultstofetchfromtheserver.
Examples:
Createandextractfirstbatch:
>curl--data@--XPOST--dump-http://localhost:8529/_api/cursor
{"query":"FORuINusersLIMIT5RETURNu","count":true,"batchSize":2}
HTTP/1.1201Created
Content-type:application/json
{
"hasMore":true,
"error":false,
"id":"26011191",
QueryResults
161
"result":[
{
"name":"user1",
"_rev":"258801191",
"_key":"258801191",
"_id":"users/258801191"
},
{
"name":"user2",
"_rev":"258801192",
"_key":"258801192",
"_id":"users/258801192"
}
],
"code":201,
"count":5
}
Extractnextbatch,stillhavemore:
>curl-XPUT--dump-http://localhost:8529/_api/cursor/26011191
HTTP/1.1200OK
Content-type:application/json
{
"hasMore":true,
"error":false,
"id":"26011191",
"result":[
{
"name":"user3",
"_rev":"258801193",
"_key":"258801193",
"_id":"users/258801193"
},
{
"name":"user4",
"_rev":"258801194",
"_key":"258801194",
"_id":"users/258801194"
}
],
"code":200,
"count":5
}
Extractnextbatch,done:
>curl-XPUT--dump-http://localhost:8529/_api/cursor/26011191
HTTP/1.1200OK
Content-type:application/json
{
"hasMore":false,
"error":false,
"result":[
{
"name":"user5",
"_rev":"258801195",
"_key":"258801195",
"_id":"users/258801195"
}
],
"code":200,
"count":5
}
DonotdothisbecausehasMorenowhasavalueoffalse:
>curl-XPUT--dump-http://localhost:8529/_api/cursor/26011191
QueryResults
162
HTTP/1.1404NotFound
Content-type:application/json
{
"errorNum":1600,
"errorMessage":"cursornotfound:disposedorunknowncursor",
"error":true,
"code":404
}
Modifyingdocuments
The_api/cursorendpointcanalsobeusedtoexecutemodifyingqueries.
ThefollowingexampleappendsavalueintothearrayarrayValueofthedocumentwithkeytestinthecollectiondocuments.Normalupdatebehavioristoreplacetheattributecompletely,andusinganupdateAQLquerywiththePUSH()functionallowstoappendtothearray.
curl--data@--XPOST--dumphttp://127.0.0.1:8529/_api/cursor
{"query":"FORdocINdocumentsFILTERdoc._key==@myKeyUPDATEdoc._keyWITH{arrayValue:PUSH(doc.arrayValue,@value)}IN
documents","bindVars":{"myKey":"test","value":42}}
HTTP/1.1201Created
Content-type:application/json;charset=utf-8
{
"result":[],
"hasMore":false,
"extra":{
"stats":{
"writesExecuted":1,
"writesIgnored":0,
"scannedFull":0,
"scannedIndex":1,
"filtered":0
},
"warnings":[]
},
"error":false,
"code":201
}
Settingamemorylimit
Tosetamemorylimitforthequery,thememoryLimitoptioncanbepassedtotheserver.Thememorylimitspecifiesthemaximumnumberofbytesthatthequeryisallowedtouse.WhenasingleAQLqueryreachesthespecifiedlimitvalue,thequerywillbeabortedwitharesourcelimitexceededexception.Inacluster,thememoryaccountingisdonepershard,sothelimitvalueiseffectivelyamemorylimitperquerypershard.
>curl--data@--XPOST--dump-http://localhost:8529/_api/cursor
{"query":"FORiIN1..100000SORTiRETURNi","memoryLimit":100000}
HTTP/1.1500InternalServerError
Server:ArangoDB
Connection:Keep-Alive
Content-Type:application/json;charset=utf-8
Content-Length:115
{"error":true,"errorMessage":"querywouldusemorememorythanallowed(whileexecuting)","code":500,"errorNum":32}
Ifnomemorylimitisspecified,thentheserverdefaultvalue(controlledbystartupoption--query.memory-limitwillbeusedforrestrictingthemaximumamountofmemorythequerycanuse.Amemorylimitvalueof0meansthatthemaximumamountofmemoryforthequeryisnotrestricted.
QueryResults
163
AccessingCursorsviaHTTP
Createcursor
createacursorandreturnthefirstresults
POST/_api/cursorAJSONobjectdescribingthequeryandqueryparameters.
AJSONobjectwiththesepropertiesisrequired:
count:indicateswhetherthenumberofdocumentsintheresultsetshouldbereturnedinthe"count"attributeoftheresult.Calculatingthe"count"attributemighthaveaperformanceimpactforsomequeriesinthefuturesothisoptionisturnedoffbydefault,and"count"isonlyreturnedwhenrequested.batchSize:maximumnumberofresultdocumentstobetransferredfromtheservertotheclientinoneroundtrip.Ifthisattributeisnotset,aserver-controlleddefaultvaluewillbeused.AbatchSizevalueof0isdisallowed.cache:flagtodeterminewhethertheAQLquerycacheshallbeused.Ifsettofalse,thenanyquerycachelookupwillbeskippedforthequery.Ifsettotrue,itwillleadtothequerycachebeingcheckedforthequeryifthequerycachemodeiseitheronordemand.memoryLimit:themaximumnumberofmemory(measuredinbytes)thatthequeryisallowedtouse.Ifset,thenthequerywillfailwitherror"resourcelimitexceeded"incaseitallocatestoomuchmemory.Avalueof0indicatesthatthereisnomemorylimit.ttl:Thetime-to-liveforthecursor(inseconds).Thecursorwillberemovedontheserverautomaticallyafterthespecifiedamountoftime.Thisisusefultoensuregarbagecollectionofcursorsthatarenotfullyfetchedbyclients.Ifnotset,aserver-definedvaluewillbeused.query:containsthequerystringtobeexecutedbindVars(object):key/valuepairsrepresentingthebindparameters.options:
failOnWarning:Whensettotrue,thequerywillthrowanexceptionandabortinsteadofproducingawarning.Thisoptionshouldbeusedduringdevelopmenttocatchpotentialissuesearly.Whentheattributeissettofalse,warningswillnotbepropagatedtoexceptionsandwillbereturnedwiththequeryresult.Thereisalsoaserverconfigurationoption--query.fail-on-warningforsettingthedefaultvalueforfailOnWarningsoitdoesnotneedtobesetonaper-querylevel.profile:Ifsettotrue,thentheadditionalqueryprofilinginformationwillbereturnedinthesub-attributeprofileoftheextrareturnattributeifthequeryresultisnotservedfromthequerycache.maxTransactionSize:Transactionsizelimitinbytes.HonoredbytheRocksDBstorageengineonly.skipInaccessibleCollections:AQLqueries(especiallygraphtraversals)willtreatcollectiontowhichauserhasnoaccessrightsasifthesecollectionswereempty.Insteadofreturningaforbiddenaccesserror,yourquerieswillexecutenormally.Thisisintendedtohelpwithcertainuse-cases:AgraphcontainsseveralcollectionsanddifferentusersexecuteAQLqueriesonthatgraph.Youcannownaturallylimittheaccessibleresultsbychangingtheaccessrightsofusersoncollections.ThisfeatureisonlyavailableintheEnterpriseEdition.maxWarningCount:Limitsthemaximumnumberofwarningsaquerywillreturn.Thenumberofwarningsaquerywillreturnislimitedto10bydefault,butthatnumbercanbeincreasedordecreasedbysettingthisattribute.intermediateCommitCount:Maximumnumberofoperationsafterwhichanintermediatecommitisperformedautomatically.HonoredbytheRocksDBstorageengineonly.satelliteSyncWait:ThisenterpriseparameterallowstoconfigurehowlongaDBServerwillhavetimetobringthesatellitecollectionsinvolvedinthequeryintosync.Thedefaultvalueis60.0(seconds).Whenthemaxtimehasbeenreachedthequerywillbestopped.fullCount:ifsettotrueandthequerycontainsaLIMITclause,thentheresultwillhaveanextraattributewiththesub-attributesstatsandfullCount,{...,"extra":{"stats":{"fullCount":123}}}.ThefullCountattributewillcontainthenumberofdocumentsintheresultbeforethelastLIMITinthequerywasapplied.Itcanbeusedtocountthenumberofdocumentsthatmatchcertainfiltercriteria,butonlyreturnasubsetofthem,inonego.ItisthussimilartoMySQL'sSQL_CALC_FOUND_ROWShint.NotethatsettingtheoptionwilldisableafewLIMIToptimizationsandmayleadtomoredocumentsbeingprocessed,andthusmakequeriesrunlonger.NotethatthefullCountattributewillonlybepresentintheresultifthequeryhasaLIMITclauseandtheLIMITclauseisactuallyusedinthequery.intermediateCommitSize:Maximumtotalsizeofoperationsafterwhichanintermediatecommitisperformedautomatically.HonoredbytheRocksDBstorageengineonly.optimizer.rules(string):Alistofto-be-includedorto-be-excludedoptimizerrulescanbeputintothisattribute,tellingtheoptimizertoincludeorexcludespecificrules.Todisablearule,prefixitsnamewitha-,toenablearule,prefixitwitha+.Thereisalsoapseudo-ruleall,whichwillmatchalloptimizerrules.
AccessingCursors
164
maxPlans:LimitsthemaximumnumberofplansthatarecreatedbytheAQLqueryoptimizer.
Thequerydetailsincludethequerystringplusoptionalqueryoptionsandbindparameters.ThesevaluesneedtobepassedinaJSONrepresentationinthebodyofthePOSTrequest.
AjsondocumentwiththesePropertiesisreturned:
HTTP201isreturnediftheresultsetcanbecreatedbytheserver.
count:thetotalnumberofresultdocumentsavailable(onlyavailableifthequerywasexecutedwiththecountattributeset)code:theHTTPstatuscodeextra:anoptionalJSONobjectwithextrainformationaboutthequeryresultcontainedinitsstatssub-attribute.Fordata-modificationqueries,theextra.statssub-attributewillcontainthenumberofmodifieddocumentsandthenumberofdocumentsthatcouldnotbemodifiedduetoanerror(ifignoreErrorsqueryoptionisspecified)cached:abooleanflagindicatingwhetherthequeryresultwasservedfromthequerycacheornot.Ifthequeryresultisservedfromthequerycache,theextrareturnattributewillnotcontainanystatssub-attributeandnoprofilesub-attribute.hasMore:Abooleanindicatorwhethertherearemoreresultsavailableforthecursorontheserverresult(anonymousjsonobject):anarrayofresultdocuments(mightbeemptyifqueryhasnoresults)error:Aflagtoindicatethatanerroroccurred(falseinthiscase)id:idoftemporarycursorcreatedontheserver(optional,seeabove)
AjsondocumentwiththesePropertiesisreturned:
HTTP400isreturnediftheJSONrepresentationismalformedorthequeryspecificationismissingfromtherequest.IftheJSONrepresentationismalformedorthequeryspecificationismissingfromtherequest,theserverwillrespondwithHTTP400.ThebodyoftheresponsewillcontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:
errorMessage:adescriptiveerrormessageIfthequeryspecificationiscomplete,theserverwillprocessthequery.Ifanerroroccursduringqueryprocessing,theserverwillrespondwithHTTP400.Again,thebodyoftheresponsewillcontaindetailsabouttheerror.Alistofqueryerrorscanbefoundhere.errorNum:theservererrornumbercode:theHTTPstatuscodeerror:booleanflagtoindicatethatanerroroccurred(trueinthiscase)
Example:Executeaqueryandextracttheresultinasinglego
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsLIMIT2RETURNp",
"count":true,
"batchSize":2
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"10541",
"_id":"products/10541",
"_rev":"_WQ47Xre--B",
"hello2":"world1"
AccessingCursors
165
},
{
"_key":"10537",
"_id":"products/10537",
"_rev":"_WQ47Xre--_",
"hello1":"world1"
}
],
"hasMore":false,
"count":2,
"cached":false,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":2,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.00009870529174804688
},
"warnings":[]
},
"error":false,
"code":201
}
Example:Executeaqueryandextractapartoftheresult
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsLIMIT5RETURNp",
"count":true,
"batchSize":2
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":201,
"result":[
{
"_key":"10525",
"_id":"products/10525",
"_rev":"_WQ47Xqa--F",
"hello5":"world1"
},
{
"_key":"10512",
"_id":"products/10512",
"_rev":"_WQ47XqW--_",
"hello1":"world1"
}
],
"hasMore":true,
"id":"10528",
"count":5,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":5,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.00009226799011230469
AccessingCursors
166
},
"warnings":[]
},
"cached":false
}
Example:Usingthequeryoption"fullCount"
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORiIN1..1000FILTERi>500LIMIT10RETURNi",
"count":true,
"options":{
"fullCount":true
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
501,
502,
503,
504,
505,
506,
507,
508,
509,
510
],
"hasMore":false,
"count":10,
"cached":false,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":0,
"scannedIndex":0,
"filtered":500,
"httpRequests":0,
"fullCount":500,
"executionTime":0.00023555755615234375
},
"warnings":[]
},
"error":false,
"code":201
}
Example:Enablinganddisablingoptimizerrules
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORiIN1..10LETa=1LETb=2FILTERa+b==3RETURNi",
"count":true,
"options":{
"maxPlans":1,
"optimizer":{
AccessingCursors
167
"rules":[
"-all",
"+remove-unnecessary-filters"
]
}
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
1,
2,
3,
4,
5,
6,
7,
8,
9,
10
],
"hasMore":false,
"count":10,
"cached":false,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":0,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.00011301040649414062
},
"warnings":[]
},
"error":false,
"code":201
}
Example:Executeadata-modificationqueryandretrievethenumberofmodifieddocuments
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsREMOVEpINproducts"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[],
"hasMore":false,
"cached":false,
"extra":{
"stats":{
"writesExecuted":2,
"writesIgnored":0,
"scannedFull":2,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.0001289844512939453
AccessingCursors
168
},
"warnings":[]
},
"error":false,
"code":201
}
Example:Executeadata-modificationquerywithoptionignoreErrors
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"REMOVE'bar'INproductsOPTIONS{ignoreErrors:true}"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[],
"hasMore":false,
"cached":false,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":1,
"scannedFull":0,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.00011205673217773438
},
"warnings":[]
},
"error":false,
"code":201
}
Example:Badquery-Missingbody
shell>curl-XPOST--dump-http://localhost:8529/_api/cursor
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"queryisempty",
"code":400,
"errorNum":1502
}
Example:Badquery-Unknowncollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
AccessingCursors
169
"query":"FORuINunknowncollLIMIT2RETURNu",
"count":true,
"batchSize":2
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"AQL:collectionnotfound:unknowncoll(whileparsing)",
"code":404,
"errorNum":1203
}
Example:Badquery-Executeadata-modificationquerythatattemptstoremoveanon-existingdocument
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"REMOVE'foo'INproducts"
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"AQL:documentnotfound(whileexecuting)",
"code":404,
"errorNum":1202
}
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsLIMIT2RETURNp",
"count":true,
"batchSize":2
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyExecuteaqueryandextractapartoftheresult
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsLIMIT5RETURNp",
"count":true,
"batchSize":2
}
EOF
AccessingCursors
170
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingthequeryoption"fullCount"
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORiIN1..1000FILTERi>500LIMIT10RETURNi",
"count":true,
"options":{
"fullCount":true
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyEnablinganddisablingoptimizerrules
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORiIN1..10LETa=1LETb=2FILTERa+b==3RETURNi",
"count":true,
"options":{
"maxPlans":1,
"optimizer":{
"rules":[
"-all",
"+remove-unnecessary-filters"
]
}
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyExecuteadata-modificationqueryandretrievethenumberofmodifieddocuments
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsREMOVEpINproducts"
}
EOF
AccessingCursors
171
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyExecuteadata-modificationquerywithoptionignoreErrors
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"REMOVE'bar'INproductsOPTIONS{ignoreErrors:true}"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyBadquery-Missingbody
shell>curl-XPOST--dump-http://localhost:8529/_api/cursor
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyBadquery-Unknowncollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORuINunknowncollLIMIT2RETURNu",
"count":true,
"batchSize":2
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyBadquery-Executeadata-modificationquerythatattemptstoremoveanon-existingdocument
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"REMOVE'foo'INproducts"
}
EOF
AccessingCursors
172
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Readnextbatchfromcursor
returnthenextresultsfromanexistingcursor
PUT/_api/cursor/{cursor-identifier}
PathParameters
cursor-identifier(required):Thenameofthecursor
Ifthecursorisstillalive,returnsanobjectwiththefollowingattributes:
id:thecursor-identifierresult:alistofdocumentsforthecurrentbatchhasMore:falseifthiswasthelastbatchcount:ifpresentthetotalnumberofelements
NotethatevenifhasMorereturnstrue,thenextcallmightstillreturnnodocuments.If,however,hasMoreisfalse,thenthecursorisexhausted.OncethehasMoreattributehasavalueoffalse,theclientcanstop.
Example:Validrequestfornextbatch
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsLIMIT5RETURNp",
"count":true,
"batchSize":2
}
EOF
shell>curl-XPUT--dump-http://localhost:8529/_api/cursor/10636
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":[
{
"_key":"10627",
"_id":"products/10627",
"_rev":"_WQ47XwS--D",
"hello3":"world1"
},
{
"_key":"10624",
"_id":"products/10624",
"_rev":"_WQ47XwS--B",
"hello2":"world1"
}
],
"hasMore":true,
"id":"10636",
"count":5,
"extra":{
"stats":{
"writesExecuted":0,
AccessingCursors
173
"writesIgnored":0,
"scannedFull":5,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.000133514404296875
},
"warnings":[]
},
"cached":false
}
Example:Missingidentifier
shell>curl-XPUT--dump-http://localhost:8529/_api/cursor
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"expectingPUT/_api/cursor/<cursor-id>",
"code":400,
"errorNum":400
}
Example:Unknownidentifier
shell>curl-XPUT--dump-http://localhost:8529/_api/cursor/123123
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"cursornotfound",
"code":404,
"errorNum":1600
}
ReturnCodes
200:TheserverwillrespondwithHTTP200incaseofsuccess.400:Ifthecursoridentifierisomitted,theserverwillrespondwithHTTP404.404:Ifnocursorwiththespecifiedidentifiercanbefound,theserverwillrespondwithHTTP404.
Examples
Validrequestfornextbatch
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsLIMIT5RETURNp",
"count":true,
"batchSize":2
}
EOF
AccessingCursors
174
shell>curl-XPUT--dump-http://localhost:8529/_api/cursor/10636
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyMissingidentifier
shell>curl-XPUT--dump-http://localhost:8529/_api/cursor
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUnknownidentifier
shell>curl-XPUT--dump-http://localhost:8529/_api/cursor/123123
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Deletecursor
disposeanexistingcursor
DELETE/_api/cursor/{cursor-identifier}
PathParameters
cursor-identifier(required):Theidofthecursor
Deletesthecursorandfreestheresourcesassociatedwithit.
Thecursorwillautomaticallybedestroyedontheserverwhentheclienthasretrievedalldocumentsfromit.TheclientcanalsoexplicitlydestroythecursoratanyearliertimeusinganHTTPDELETErequest.ThecursoridmustbeincludedaspartoftheURL.
Note:theserverwillalsodestroyabandonedcursorsautomaticallyafteracertainserver-controlledtimeouttoavoidresourceleakage.
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsLIMIT5RETURNp",
"count":true,
"batchSize":2
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
AccessingCursors
175
{
"error":false,
"code":201,
"result":[
{
"_key":"10557",
"_id":"products/10557",
"_rev":"_WQ47Xsm--B",
"hello2":"world1"
},
{
"_key":"10566",
"_id":"products/10566",
"_rev":"_WQ47Xsq--B",
"hello5":"world1"
}
],
"hasMore":true,
"id":"10569",
"count":5,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":5,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.00009655952453613281
},
"warnings":[]
},
"cached":false
}
shell>curl-XDELETE--dump-http://localhost:8529/_api/cursor/10569
ReturnCodes
202:isreturnediftheserverisawareofthecursor.404:isreturnediftheserverisnotawareofthecursor.Itisalsoreturnedifacursorisusedafterithasbeendestroyed.
Examples
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORpINproductsLIMIT5RETURNp",
"count":true,
"batchSize":2
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
AccessingCursors
176
HTTPInterfaceforAQLQueries
Explainingandparsingqueries
ArangoDBhasanHTTPinterfacetosyntacticallyvalidateAQLqueries.Furthermore,itoffersanHTTPinterfacetoretrievetheexecutionplanforanyvalidAQLquery.
BothfunctionalitiesdonotactuallyexecutethesuppliedAQLquery,butonlyinspectitandreturnmetainformationaboutit.
ExplainanAQLquery
explainanAQLqueryandreturninformationaboutit
POST/_api/explainAJSONobjectdescribingthequeryandqueryparameters.
AJSONobjectwiththesepropertiesisrequired:
query:thequerywhichyouwantexplained;Ifthequeryreferencesanybindvariables,thesemustalsobepassedintheattributebindVars.Additionaloptionsforthequerycanbepassedintheoptionsattribute.options:
optimizer.rules(string):anarrayofto-be-includedorto-be-excludedoptimizerrulescanbeputintothisattribute,tellingtheoptimizertoincludeorexcludespecificrules.Todisablearule,prefixitsnamewitha-,toenablearule,prefixitwitha+.Thereisalsoapseudo-ruleall,whichwillmatchalloptimizerrules.maxNumberOfPlans:anoptionalmaximumnumberofplansthattheoptimizerisallowedtogenerate.Settingthisattributetoalowvalueallowstoputacapontheamountofworktheoptimizerdoes.allPlans:ifsettotrue,allpossibleexecutionplanswillbereturned.Thedefaultisfalse,meaningonlytheoptimalplanwillbereturned.
bindVars(object):key/valuepairsrepresentingthebindparameters.
ToexplainhowanAQLquerywouldbeexecutedontheserver,thequerystringcanbesenttotheserverviaanHTTPPOSTrequest.Theserverwillthenvalidatethequeryandcreateanexecutionplanforit.Theexecutionplanwillbereturned,butthequerywillnotbeexecuted.
Theexecutionplanthatisreturnedbytheservercanbeusedtoestimatetheprobableperformanceofthequery.Thoughtheactualperformancewilldependonmanydifferentfactors,theexecutionplannormallycanprovidesomeroughestimatesontheamountofworktheserverneedstodoinordertoactuallyrunthequery.
Bydefault,theexplainoperationwillreturntheoptimalplanaschosenbythequeryoptimizerTheoptimalplanistheplanwiththelowesttotalestimatedcost.Theplanwillbereturnedintheattributeplanoftheresponseobject.IftheoptionallPlansisspecifiedintherequest,theresultwillcontainallplanscreatedbytheoptimizer.Theplanswillthenbereturnedintheattributeplans.
Theresultwillalsocontainanattributewarnings,whichisanarrayofwarningsthatoccurredduringoptimizationorexecutionplancreation.Additionally,astatsattributeiscontainedintheresultwithsomeoptimizerstatistics.IfallPlansissettofalse,theresultwillcontainanattributecacheablethatstateswhetherthequeryresultscanbecachedontheserverifthequeryresultcachewereused.ThecacheableattributeisnotpresentwhenallPlansissettotrue.
EachplanintheresultisaJSONobjectwiththefollowingattributes:
nodes:thearrayofexecutionnodesoftheplan.Thearrayofavailablenodetypescanbefoundhere
estimatedCost:thetotalestimatedcostfortheplan.Iftherearemultipleplans,theoptimizerwillchoosetheplanwiththelowesttotalcost.
collections:anarrayofcollectionsusedinthequery
rules:anarrayofrulestheoptimizerapplied.Anoverviewoftheavailablerulescanbefoundhere
variables:arrayofvariablesusedinthequery(note:thismaycontaininternalvariablescreatedbytheoptimizer)
Example:
AQLQueries
177
Validquery
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORpINproductsRETURNp"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"plan":{
"nodes":[
{
"type":"SingletonNode",
"dependencies":[],
"id":1,
"estimatedCost":1,
"estimatedNrItems":1
},
{
"type":"EnumerateCollectionNode",
"dependencies":[
1
],
"id":2,
"estimatedCost":12,
"estimatedNrItems":10,
"database":"_system",
"collection":"products",
"random":false,
"satellite":false,
"outVariable":{
"id":0,
"name":"p"
}
},
{
"type":"ReturnNode",
"dependencies":[
2
],
"id":3,
"estimatedCost":22,
"estimatedNrItems":10,
"inVariable":{
"id":0,
"name":"p"
}
}
],
"rules":[],
"collections":[
{
"name":"products",
"type":"read"
}
],
"variables":[
{
"id":0,
"name":"p"
}
],
"estimatedCost":22,
"estimatedNrItems":10,
"initialize":true
},
"cacheable":true,
"warnings":[],
"stats":{
"rulesExecuted":30,
"rulesSkipped":0,
AQLQueries
178
"plansCreated":1
},
"error":false,
"code":200
}
Example:Aplanwithsomeoptimizerrulesapplied
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORpINproductsLETa=p.idFILTERa==4LETname=p.nameSORTp.idLIMIT1RETURNname"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"plan":{
"nodes":[
{
"type":"SingletonNode",
"dependencies":[],
"id":1,
"estimatedCost":1,
"estimatedNrItems":1
},
{
"type":"IndexNode",
"dependencies":[
1
],
"id":11,
"estimatedCost":4.321928094887362,
"estimatedNrItems":1,
"database":"_system",
"collection":"products",
"satellite":false,
"outVariable":{
"id":0,
"name":"p"
},
"indexes":[
{
"id":"11343",
"type":"skiplist",
"fields":[
"id"
],
"unique":false,
"sparse":false,
"deduplicate":true
}
],
"condition":{
"type":"n-aryor",
"subNodes":[
{
"type":"n-aryand",
"subNodes":[
{
"type":"compare==",
"subNodes":[
{
"type":"attributeaccess",
"name":"id",
"subNodes":[
{
"type":"reference",
AQLQueries
179
"name":"p",
"id":0
}
]
},
{
"type":"value",
"value":4
}
]
}
]
}
]
},
"reverse":false
},
{
"type":"CalculationNode",
"dependencies":[
11
],
"id":4,
"estimatedCost":5.321928094887362,
"estimatedNrItems":1,
"expression":{
"type":"compare==",
"subNodes":[
{
"type":"attributeaccess",
"name":"id",
"subNodes":[
{
"type":"reference",
"name":"p",
"id":0
}
]
},
{
"type":"value",
"value":4
}
]
},
"outVariable":{
"id":4,
"name":"3"
},
"canThrow":false,
"expressionType":"simple"
},
{
"type":"FilterNode",
"dependencies":[
4
],
"id":5,
"estimatedCost":6.321928094887362,
"estimatedNrItems":1,
"inVariable":{
"id":4,
"name":"3"
}
},
{
"type":"LimitNode",
"dependencies":[
5
],
"id":9,
"estimatedCost":7.321928094887362,
"estimatedNrItems":1,
"offset":0,
"limit":1,
"fullCount":false
AQLQueries
180
},
{
"type":"CalculationNode",
"dependencies":[
9
],
"id":6,
"estimatedCost":8.321928094887362,
"estimatedNrItems":1,
"expression":{
"type":"attributeaccess",
"name":"name",
"subNodes":[
{
"type":"reference",
"name":"p",
"id":0
}
]
},
"outVariable":{
"id":2,
"name":"name"
},
"canThrow":false,
"expressionType":"attribute"
},
{
"type":"ReturnNode",
"dependencies":[
6
],
"id":10,
"estimatedCost":9.321928094887362,
"estimatedNrItems":1,
"inVariable":{
"id":2,
"name":"name"
}
}
],
"rules":[
"move-calculations-up",
"remove-redundant-calculations",
"remove-unnecessary-calculations",
"move-calculations-up-2",
"use-indexes",
"use-index-for-sort",
"remove-unnecessary-calculations-2",
"move-calculations-down"
],
"collections":[
{
"name":"products",
"type":"read"
}
],
"variables":[
{
"id":6,
"name":"5"
},
{
"id":4,
"name":"3"
},
{
"id":2,
"name":"name"
},
{
"id":1,
"name":"a"
},
{
"id":0,
AQLQueries
181
"name":"p"
}
],
"estimatedCost":9.321928094887362,
"estimatedNrItems":1,
"initialize":true
},
"cacheable":true,
"warnings":[],
"stats":{
"rulesExecuted":30,
"rulesSkipped":0,
"plansCreated":1
},
"error":false,
"code":200
}
Example:Usingsomeoptions
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORpINproductsLETa=p.idFILTERa==4LETname=p.nameSORTp.idLIMIT1RETURNname",
"options":{
"maxNumberOfPlans":2,
"allPlans":true,
"optimizer":{
"rules":[
"-all",
"+use-index-for-sort",
"+use-index-range"
]
}
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"plans":[
{
"nodes":[
{
"type":"SingletonNode",
"dependencies":[],
"id":1,
"estimatedCost":1,
"estimatedNrItems":1
},
{
"type":"IndexNode",
"dependencies":[
1
],
"id":11,
"estimatedCost":11,
"estimatedNrItems":10,
"database":"_system",
"collection":"products",
"satellite":false,
"outVariable":{
"id":0,
"name":"p"
},
"indexes":[
{
"id":"11389",
AQLQueries
182
"type":"skiplist",
"fields":[
"id"
],
"unique":false,
"sparse":false,
"deduplicate":true
}
],
"condition":{
},
"reverse":false
},
{
"type":"CalculationNode",
"dependencies":[
11
],
"id":3,
"estimatedCost":21,
"estimatedNrItems":10,
"expression":{
"type":"attributeaccess",
"name":"id",
"subNodes":[
{
"type":"reference",
"name":"p",
"id":0
}
]
},
"outVariable":{
"id":1,
"name":"a"
},
"canThrow":false,
"expressionType":"attribute"
},
{
"type":"CalculationNode",
"dependencies":[
3
],
"id":4,
"estimatedCost":31,
"estimatedNrItems":10,
"expression":{
"type":"compare==",
"subNodes":[
{
"type":"reference",
"name":"a",
"id":1
},
{
"type":"value",
"value":4
}
]
},
"outVariable":{
"id":4,
"name":"3"
},
"canThrow":false,
"expressionType":"simple"
},
{
"type":"FilterNode",
"dependencies":[
4
],
"id":5,
"estimatedCost":41,
"estimatedNrItems":10,
AQLQueries
183
"inVariable":{
"id":4,
"name":"3"
}
},
{
"type":"CalculationNode",
"dependencies":[
5
],
"id":6,
"estimatedCost":51,
"estimatedNrItems":10,
"expression":{
"type":"attributeaccess",
"name":"name",
"subNodes":[
{
"type":"reference",
"name":"p",
"id":0
}
]
},
"outVariable":{
"id":2,
"name":"name"
},
"canThrow":false,
"expressionType":"attribute"
},
{
"type":"CalculationNode",
"dependencies":[
6
],
"id":7,
"estimatedCost":61,
"estimatedNrItems":10,
"expression":{
"type":"attributeaccess",
"name":"id",
"subNodes":[
{
"type":"reference",
"name":"p",
"id":0
}
]
},
"outVariable":{
"id":6,
"name":"5"
},
"canThrow":false,
"expressionType":"attribute"
},
{
"type":"LimitNode",
"dependencies":[
7
],
"id":9,
"estimatedCost":62,
"estimatedNrItems":1,
"offset":0,
"limit":1,
"fullCount":false
},
{
"type":"ReturnNode",
"dependencies":[
9
],
"id":10,
"estimatedCost":63,
AQLQueries
184
"estimatedNrItems":1,
"inVariable":{
"id":2,
"name":"name"
}
}
],
"rules":[
"use-index-for-sort"
],
"collections":[
{
"name":"products",
"type":"read"
}
],
"variables":[
{
"id":6,
"name":"5"
},
{
"id":4,
"name":"3"
},
{
"id":2,
"name":"name"
},
{
"id":1,
"name":"a"
},
{
"id":0,
"name":"p"
}
],
"estimatedCost":63,
"estimatedNrItems":1,
"initialize":true
}
],
"warnings":[],
"stats":{
"rulesExecuted":1,
"rulesSkipped":29,
"plansCreated":1
},
"error":false,
"code":200
}
Example:Returningallplans
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORpINproductsFILTERp.id==25RETURNp",
"options":{
"allPlans":true
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"plans":[
AQLQueries
185
{
"nodes":[
{
"type":"SingletonNode",
"dependencies":[],
"id":1,
"estimatedCost":1,
"estimatedNrItems":1
},
{
"type":"IndexNode",
"dependencies":[
1
],
"id":6,
"estimatedCost":1.99,
"estimatedNrItems":1,
"database":"_system",
"collection":"products",
"satellite":false,
"outVariable":{
"id":0,
"name":"p"
},
"indexes":[
{
"id":"11305",
"type":"hash",
"fields":[
"id"
],
"selectivityEstimate":1,
"unique":false,
"sparse":false,
"deduplicate":true
}
],
"condition":{
"type":"n-aryor",
"subNodes":[
{
"type":"n-aryand",
"subNodes":[
{
"type":"compare==",
"subNodes":[
{
"type":"attributeaccess",
"name":"id",
"subNodes":[
{
"type":"reference",
"name":"p",
"id":0
}
]
},
{
"type":"value",
"value":25
}
]
}
]
}
]
},
"reverse":false
},
{
"type":"ReturnNode",
"dependencies":[
6
],
"id":5,
"estimatedCost":2.99,
AQLQueries
186
"estimatedNrItems":1,
"inVariable":{
"id":0,
"name":"p"
}
}
],
"rules":[
"use-indexes",
"remove-filter-covered-by-index",
"remove-unnecessary-calculations-2"
],
"collections":[
{
"name":"products",
"type":"read"
}
],
"variables":[
{
"id":2,
"name":"1"
},
{
"id":0,
"name":"p"
}
],
"estimatedCost":2.99,
"estimatedNrItems":1,
"initialize":true
}
],
"warnings":[],
"stats":{
"rulesExecuted":30,
"rulesSkipped":0,
"plansCreated":1
},
"error":false,
"code":200
}
Example:Aquerythatproducesawarning
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORiIN1..10RETURN1/0"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"plan":{
"nodes":[
{
"type":"SingletonNode",
"dependencies":[],
"id":1,
"estimatedCost":1,
"estimatedNrItems":1
},
{
"type":"CalculationNode",
"dependencies":[
1
],
AQLQueries
187
"id":2,
"estimatedCost":2,
"estimatedNrItems":1,
"expression":{
"type":"range",
"subNodes":[
{
"type":"value",
"value":1
},
{
"type":"value",
"value":10
}
]
},
"outVariable":{
"id":2,
"name":"1"
},
"canThrow":false,
"expressionType":"simple"
},
{
"type":"CalculationNode",
"dependencies":[
2
],
"id":4,
"estimatedCost":3,
"estimatedNrItems":1,
"expression":{
"type":"value",
"value":null
},
"outVariable":{
"id":4,
"name":"3"
},
"canThrow":false,
"expressionType":"json"
},
{
"type":"EnumerateListNode",
"dependencies":[
4
],
"id":3,
"estimatedCost":13,
"estimatedNrItems":10,
"inVariable":{
"id":2,
"name":"1"
},
"outVariable":{
"id":0,
"name":"i"
}
},
{
"type":"ReturnNode",
"dependencies":[
3
],
"id":5,
"estimatedCost":23,
"estimatedNrItems":10,
"inVariable":{
"id":4,
"name":"3"
}
}
],
"rules":[
"move-calculations-up",
"move-calculations-up-2"
AQLQueries
188
],
"collections":[],
"variables":[
{
"id":4,
"name":"3"
},
{
"id":2,
"name":"1"
},
{
"id":0,
"name":"i"
}
],
"estimatedCost":23,
"estimatedNrItems":10,
"initialize":true
},
"cacheable":false,
"warnings":[
{
"code":1562,
"message":"divisionbyzero"
}
],
"stats":{
"rulesExecuted":30,
"rulesSkipped":0,
"plansCreated":1
},
"error":false,
"code":200
}
Example:Invalidquery(missingbindparameter)
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"[email protected]"
}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"novaluespecifiedfordeclaredbindparameter'id'(whileparsing)",
"code":400,
"errorNum":1551
}
Example:ThedatareturnedintheplanattributeoftheresultcontainsoneelementperAQLtop-levelstatement(i.e.FOR,RETURN,FILTERetc.).Ifthequeryoptimizerremovedsomeunnecessarystatements,theresultmightalsocontainlesselementsthanthereweretop-levelstatementsintheAQLquery.
Thefollowingexampleshowsaquerywithanon-sensiblefilterconditionthattheoptimizerhasremovedsothattherearelesstop-levelstatements.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
AQLQueries
189
{"query":"FORiIN[1,2,3]FILTER1==2RETURNi"}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"plan":{
"nodes":[
{
"type":"SingletonNode",
"dependencies":[],
"id":1,
"estimatedCost":1,
"estimatedNrItems":1
},
{
"type":"CalculationNode",
"dependencies":[
1
],
"id":2,
"estimatedCost":2,
"estimatedNrItems":1,
"expression":{
"type":"array",
"subNodes":[
{
"type":"value",
"value":1
},
{
"type":"value",
"value":2
},
{
"type":"value",
"value":3
}
]
},
"outVariable":{
"id":2,
"name":"1"
},
"canThrow":false,
"expressionType":"json"
},
{
"type":"NoResultsNode",
"dependencies":[
2
],
"id":7,
"estimatedCost":0.5,
"estimatedNrItems":0
},
{
"type":"EnumerateListNode",
"dependencies":[
7
],
"id":3,
"estimatedCost":0.5,
"estimatedNrItems":0,
"inVariable":{
"id":2,
"name":"1"
},
"outVariable":{
"id":0,
"name":"i"
}
},
{
AQLQueries
190
"type":"ReturnNode",
"dependencies":[
3
],
"id":6,
"estimatedCost":0.5,
"estimatedNrItems":0,
"inVariable":{
"id":0,
"name":"i"
}
}
],
"rules":[
"move-calculations-up",
"move-filters-up",
"remove-unnecessary-filters",
"remove-unnecessary-calculations"
],
"collections":[],
"variables":[
{
"id":4,
"name":"3"
},
{
"id":2,
"name":"1"
},
{
"id":0,
"name":"i"
}
],
"estimatedCost":0.5,
"estimatedNrItems":0,
"initialize":true
},
"cacheable":true,
"warnings":[],
"stats":{
"rulesExecuted":30,
"rulesSkipped":0,
"plansCreated":1
},
"error":false,
"code":200
}
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORpINproductsRETURNp"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyAplanwithsomeoptimizerrulesapplied
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORpINproductsLETa=p.idFILTERa==4LETname=p.nameSORTp.id
LIMIT1RETURNname"
AQLQueries
191
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingsomeoptions
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORpINproductsLETa=p.idFILTERa==4LETname=p.nameSORTp.id
LIMIT1RETURNname",
"options":{
"maxNumberOfPlans":2,
"allPlans":true,
"optimizer":{
"rules":[
"-all",
"+use-index-for-sort",
"+use-index-range"
]
}
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyReturningallplans
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"FORpINproductsFILTERp.id==25RETURNp",
"options":{
"allPlans":true
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyAquerythatproducesawarning
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
AQLQueries
192
{
"query":"FORiIN1..10RETURN1/0"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyInvalidquery(missingbindparameter)
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{
"query":"[email protected]"
}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyThedatareturnedintheplanattributeoftheresultcontainsoneelementperAQLtop-levelstatement(i.e.FOR,RETURN,FILTERetc.).Ifthequeryoptimizerremovedsomeunnecessarystatements,theresultmightalsocontainlesselementsthanthereweretop-levelstatementsintheAQLquery.Thefollowingexampleshowsaquerywithanon-sensiblefilterconditionthattheoptimizerhasremovedsothattherearelesstop-levelstatements.
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF
{"query":"FORiIN[1,2,3]FILTER1==2RETURNi"}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
ParseanAQLquery
parseanAQLqueryandreturninformationaboutit
POST/_api/query
Thisendpointisforqueryvalidationonly.Toactuallyquerythedatabase,see/api/cursor.
AJSONobjectwiththesepropertiesisrequired:
query:Tovalidateaquerystringwithoutexecutingit,thequerystringcanbepassedtotheserverviaanHTTPPOSTrequest.
Example:aValidquery
AQLQueries
193
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/query<<EOF
{"query":"[email protected]"}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"parsed":true,
"collections":[
"products"
],
"bindVars":[
"name"
],
"ast":[
{
"type":"root",
"subNodes":[
{
"type":"for",
"subNodes":[
{
"type":"variable",
"name":"p",
"id":0
},
{
"type":"collection",
"name":"products"
}
]
},
{
"type":"filter",
"subNodes":[
{
"type":"compare==",
"subNodes":[
{
"type":"attributeaccess",
"name":"name",
"subNodes":[
{
"type":"reference",
"name":"p",
"id":0
}
]
},
{
"type":"parameter",
"name":"name"
}
]
}
]
},
{
"type":"limit",
"subNodes":[
{
"type":"value",
"value":0
},
{
"type":"value",
"value":2
}
]
},
{
"type":"return",
AQLQueries
194
"subNodes":[
{
"type":"attributeaccess",
"name":"n",
"subNodes":[
{
"type":"reference",
"name":"p",
"id":0
}
]
}
]
}
]
}
]
}
Example:anInvalidquery
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/query<<EOF
{"query":"[email protected]"}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"syntaxerror,unexpectedassignmentnear'[email protected]'atposition1:33",
"code":400,
"errorNum":1501
}
ReturnCodes
200:Ifthequeryisvalid,theserverwillrespondwithHTTP200andreturnthenamesofthebindparametersitfoundinthequery(ifany)inthebindVarsattributeoftheresponse.Itwillalsoreturnanarrayofthecollectionsusedinthequeryinthecollectionsattribute.Ifaquerycanbeparsedsuccessfully,theastattributeofthereturnedJSONwillcontaintheabstractsyntaxtreerepresentationofthequery.TheformatoftheastissubjecttochangeinfutureversionsofArangoDB,butitcanbeusedtoinspecthowArangoDBinterpretsagivenquery.Notethattheabstractsyntaxtreewillbereturnedwithoutanyoptimizationsappliedtoit.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,orifthequerycontainsaparseerror.ThebodyoftheresponsewillcontaintheerrordetailsembeddedinaJSONobject.
Examples
aValidquery
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/query<<EOF
{"query":"[email protected]"}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyanInvalidquery
AQLQueries
195
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/query<<EOF
{"query":"[email protected]"}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Querytracking
ArangoDBhasanHTTPinterfaceforretrievingthelistsofcurrentlyexecutingAQLqueriesandthelistofslowAQLqueries.InordertomakemeaningfuluseoftheseAPIs,querytrackingneedstobeenabledinthedatabasetheHTTPrequestisexecutedfor.
ReturnsthepropertiesfortheAQLquerytracking
returnstheconfigurationfortheAQLquerytracking
GET/_api/query/properties
Returnsthecurrentquerytrackingconfiguration.TheconfigurationisaJSONobjectwiththefollowingproperties:
enabled:ifsettotrue,thenquerieswillbetracked.Ifsettofalse,neitherqueriesnorslowquerieswillbetracked.
trackSlowQueries:ifsettotrue,thenslowquerieswillbetrackedinthelistofslowqueriesiftheirruntimeexceedsthevaluesetinslowQueryThreshold.Inorderforslowqueriestobetracked,theenabledpropertymustalsobesettotrue.
trackBindVars:ifsettotrue,thenbindvariablesusedinquerieswillbetracked.
maxSlowQueries:themaximumnumberofslowqueriestokeepinthelistofslowqueries.Ifthelistofslowqueriesisfull,theoldestentryinitwillbediscardedwhenadditionalslowqueriesoccur.
slowQueryThreshold:thethresholdvaluefortreatingaqueryasslow.Aquerywitharuntimegreaterorequaltothisthresholdvaluewillbeputintothelistofslowquerieswhenslowquerytrackingisenabled.ThevalueforslowQueryThresholdisspecifiedinseconds.
maxQueryStringLength:themaximumquerystringlengthtokeepinthelistofqueries.Querystringscanhavearbitrarylengths,andthispropertycanbeusedtosavememoryincaseverylongquerystringsareused.Thevalueisspecifiedinbytes.
ReturnCodes
200:Isreturnedifpropertieswereretrievedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,
ChangesthepropertiesfortheAQLquerytracking
changestheconfigurationfortheAQLquerytracking
PUT/_api/query/properties
AJSONobjectwiththesepropertiesisrequired:
maxSlowQueries:Themaximumnumberofslowqueriestokeepinthelistofslowqueries.Ifthelistofslowqueriesisfull,theoldestentryinitwillbediscardedwhenadditionalslowqueriesoccur.slowQueryThreshold:Thethresholdvaluefortreatingaqueryasslow.Aquerywitharuntimegreaterorequaltothisthresholdvaluewillbeputintothelistofslowquerieswhenslowquerytrackingisenabled.ThevalueforslowQueryThresholdisspecifiedinseconds.enabled:Ifsettotrue,thenquerieswillbetracked.Ifsettofalse,neitherqueriesnorslowquerieswillbetracked.maxQueryStringLength:Themaximumquerystringlengthtokeepinthelistofqueries.Querystringscanhavearbitrarylengths,andthispropertycanbeusedtosavememoryincaseverylongquerystringsareused.Thevalueisspecifiedinbytes.trackSlowQueries:Ifsettotrue,thenslowquerieswillbetrackedinthelistofslowqueriesiftheirruntimeexceedsthevalueset
AQLQueries
196
inslowQueryThreshold.Inorderforslowqueriestobetracked,theenabledpropertymustalsobesettotrue.
trackBindVars:Ifsettotrue,thenthebindvariablesusedinquerieswillbetrackedalongwithqueries.
ThepropertiesneedtobepassedintheattributepropertiesinthebodyoftheHTTPrequest.propertiesneedstobeaJSONobject.
Afterthepropertieshavebeenchanged,thecurrentsetofpropertieswillbereturnedintheHTTPresponse.
ReturnCodes
200:Isreturnedifthepropertieswerechangedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,
ReturnsthecurrentlyrunningAQLqueries
returnsalistofcurrentlyrunningAQLqueries
GET/_api/query/current
ReturnsanarraycontainingtheAQLqueriescurrentlyrunningintheselecteddatabase.EachqueryisaJSONobjectwiththefollowingattributes:
id:thequery'sid
query:thequerystring(potentiallytruncated)
bindVars:thebindparametervaluesusedbythequery
started:thedateandtimewhenthequerywasstarted
runTime:thequery'sruntimeuptothepointthelistofquerieswasqueried
state:thequery'scurrentexecutionstate(asastring)
ReturnCodes
200:Isreturnedwhenthelistofqueriescanberetrievedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,
ReturnsthelistofslowAQLqueries
returnsalistofslowrunningAQLqueries
GET/_api/query/slow
ReturnsanarraycontainingthelastAQLqueriesthatarefinishedandhaveexceededtheslowquerythresholdintheselecteddatabase.ThemaximumamountofqueriesinthelistcanbecontrolledbysettingthequerytrackingpropertymaxSlowQueries.ThethresholdfortreatingaqueryasslowcanbeadjustedbysettingthequerytrackingpropertyslowQueryThreshold.
EachqueryisaJSONobjectwiththefollowingattributes:
id:thequery'sid
query:thequerystring(potentiallytruncated)
bindVars:thebindparametervaluesusedbythequery
started:thedateandtimewhenthequerywasstarted
runTime:thequery'stotalruntime
state:thequery'scurrentexecutionstate(willalwaysbe"finished"forthelistofslowqueries)
ReturnCodes
200:Isreturnedwhenthelistofqueriescanberetrievedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,
ClearsthelistofslowAQLqueries
AQLQueries
197
clearsthelistofslowAQLqueries
DELETE/_api/query/slow
ClearsthelistofslowAQLqueries
ReturnCodes
200:TheserverwillrespondwithHTTP200whenthelistofquerieswasclearedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest.
Killingqueries
RunningAQLqueriescanalsobekilledontheserver.ArangoDBprovidesakillfacilityviaanHTTPinterface.Tokillarunningquery,itsid(asreturnedforthequeryinthelistofcurrentlyrunningqueries)mustbespecified.Thekillflagofthequerywillthenbeset,andthequerywillbeabortedassoonasitreachesacancelationpoint.
KillsarunningAQLquery
killsanAQLquery
DELETE/_api/query/{query-id}
PathParameters
query-id(required):Theidofthequery.
Killsarunningquery.Thequerywillbeterminatedatthenextcancelationpoint.
ReturnCodes
200:TheserverwillrespondwithHTTP200whenthequerywasstillrunningwhenthekillrequestwasexecutedandthequery'skillflagwasset.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest.404:TheserverwillrespondwithHTTP404whennoquerywiththespecifiedidwasfound.
AQLQueries
198
HTTPInterfacefortheAQLquerycacheThissectiondescribestheAPImethodsforcontrollingtheAQLquerycache.
ClearsanyresultsintheAQLquerycache
clearstheAQLquerycache
DELETE/_api/query-cache
clearsthequerycache
ReturnCodes
200:TheserverwillrespondwithHTTP200whenthecachewasclearedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest.
ReturnstheglobalpropertiesfortheAQLquerycache
returnstheglobalconfigurationfortheAQLquerycache
GET/_api/query-cache/properties
ReturnstheglobalAQLquerycacheconfiguration.TheconfigurationisaJSONobjectwiththefollowingproperties:
mode:themodetheAQLquerycacheoperatesin.Themodeisoneofthefollowingvalues:off,onordemand.
maxResults:themaximumnumberofqueryresultsthatwillbestoredperdatabase-specificcache.
ReturnCodes
200:Isreturnedifthepropertiescanberetrievedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,
GloballyadjuststheAQLqueryresultcacheproperties
changestheconfigurationfortheAQLquerycache
PUT/_api/query-cache/properties
Afterthepropertieshavebeenchanged,thecurrentsetofpropertieswillbereturnedintheHTTPresponse.
Note:changingthepropertiesmayinvalidateallresultsinthecache.TheglobalpropertiesforAQLquerycache.ThepropertiesneedtobepassedintheattributepropertiesinthebodyoftheHTTPrequest.propertiesneedstobeaJSONobjectwiththefollowingproperties:
AJSONobjectwiththesepropertiesisrequired:
mode:themodetheAQLquerycacheshouldoperatein.Possiblevaluesareoff,onordemand.maxResults:themaximumnumberofqueryresultsthatwillbestoredperdatabase-specificcache.
ReturnCodes
200:Isreturnedifthepropertieswerechangedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,
AQLQueryCache
199
HTTPInterfaceforAQLUserFunctionsManagement
AQLUserFunctionsManagement
ThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingAQLuserfunctions.AQLuserfunctionsareameanstoextendthefunctionalityofArangoDB'squerylanguage(AQL)withuser-definedJavaScriptcode.
ForanoverviewofhowAQLuserfunctionsandtheirimplications,pleaserefertotheExtendingAQLchapter.
TheHTTPinterfaceprovidesanAPIforadding,deleting,andlistingpreviouslyregisteredAQLuserfunctions.
Alluserfunctionsmanagedthroughthisinterfacewillbestoredinthesystemcollection_aqlfunctions.Documentsinthiscollectionshouldnotbeaccesseddirectly,butonlyviathededicatedinterfaces.
CreateAQLuserfunction
createanewAQLuserfunction
POST/_api/aqlfunction
AJSONobjectwiththesepropertiesisrequired:
isDeterministic:anoptionalbooleanvaluetoindicatethatthefunctionresultsarefullydeterministic(functionreturnvaluesolelydependsontheinputvalueandreturnvalueisthesameforrepeatedcallswithsameinput).TheisDeterministicattributeiscurrentlynotusedbutmaybeusedlaterforoptimisations.code:astringrepresentationofthefunctionbody.name:thefullyqualifiednameoftheuserfunctions.
Incaseofsuccess,thereturnedJSONobjecthasthefollowingproperties:
error:booleanflagtoindicatethatanerroroccurred(falseinthiscase)
code:theHTTPstatuscode
ThebodyoftheresponsewillcontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:
error:booleanflagtoindicatethatanerroroccurred(trueinthiscase)
code:theHTTPstatuscode
errorNum:theservererrornumber
errorMessage:adescriptiveerrormessage
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/aqlfunction<<EOF
{
"name":"myfunctions::temperature::celsiustofahrenheit",
"code":"function(celsius){returncelsius*1.8+32;}"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":201
}
ReturnCodes
AQLUserFunctionsManagement
200
200:Ifthefunctionalreadyexistedandwasreplacedbythecall,theserverwillrespondwithHTTP200.201:Ifthefunctioncanberegisteredbytheserver,theserverwillrespondwithHTTP201.400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest,theserverwillrespondwithHTTP400.
Examples
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/aqlfunction<<EOF
{
"name":"myfunctions::temperature::celsiustofahrenheit",
"code":"function(celsius){returncelsius*1.8+32;}"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":201
}
RemoveexistingAQLuserfunction
removeanexistingAQLuserfunction
DELETE/_api/aqlfunction/{name}
PathParameters
name(required):thenameoftheAQLuserfunction.
QueryParameters
group(optional):Ifsettotrue,thenthefunctionnameprovidedinnameistreatedasanamespaceprefix,andallfunctionsinthespecifiednamespacewillbedeleted.Ifsettofalse,thefunctionnameprovidedinnamemustbefullyqualified,includinganynamespaces.
RemovesanexistingAQLuserfunction,identifiedbyname.
Incaseofsuccess,thereturnedJSONobjecthasthefollowingproperties:
error:booleanflagtoindicatethatanerroroccurred(falseinthiscase)
code:theHTTPstatuscode
ThebodyoftheresponsewillcontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:
error:booleanflagtoindicatethatanerroroccurred(trueinthiscase)
code:theHTTPstatuscode
errorNum:theservererrornumber
errorMessage:adescriptiveerrormessage
Example:deletesafunction:
shell>curl-XDELETE--dump-http://localhost:8529/_api/aqlfunction/square::x::y
AQLUserFunctionsManagement
201
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200
}
Example:functionnotfound:
shell>curl-XDELETE--dump-http://localhost:8529/_api/aqlfunction/myfunction::x::y
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"code":404,
"errorNum":1582,
"errorMessage":"userfunction'%s()'notfound"
}
ReturnCodes
200:Ifthefunctioncanberemovedbytheserver,theserverwillrespondwithHTTP200.400:Iftheuserfunctionnameismalformed,theserverwillrespondwithHTTP400.404:Ifthespecifieduseruserfunctiondoesnotexist,theserverwillrespondwithHTTP404.
Examples
deletesafunction:
shell>curl-XDELETE--dump-http://localhost:8529/_api/aqlfunction/square::x::y
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200
}
functionnotfound:
shell>curl-XDELETE--dump-http://localhost:8529/_api/aqlfunction/myfunction::x::y
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
ReturnregisteredAQLuserfunctions
AQLUserFunctionsManagement
202
getsallreqisteredAQLuserfunctions
GET/_api/aqlfunction
QueryParameters
namespace(optional):ReturnsallregisteredAQLuserfunctionsfromnamespacenamespace.
ReturnsallregisteredAQLuserfunctions.
ThecallwillreturnaJSONarraywithalluserfunctionsfound.Eachuserfunctionwillatleasthavethefollowingattributes:
name:Thefullyqualifiednameoftheuserfunction
code:Astringrepresentationofthefunctionbody
Example:
shell>curl--dump-http://localhost:8529/_api/aqlfunction
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"name":"myfunctions::temperature::celsiustofahrenheit",
"code":"function(celsius){returncelsius*1.8+32;}"
}
]
ReturnCodes
200:ifsuccessHTTP200isreturned.
Examples
shell>curl--dump-http://localhost:8529/_api/aqlfunction
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"name":"myfunctions::temperature::celsiustofahrenheit",
"code":"function(celsius){returncelsius*1.8+32;}"
}
]
AQLUserFunctionsManagement
203
HTTPInterfaceforSimpleQueries
SimpleQueries
ThisisanintroductiontoArangoDB'sHTTPinterfaceforsimplequeries.
Simplequeriescanbeusedifthequeryconditionisstraightforwardsimple,i.e.,adocumentreference,alldocuments,aquery-by-example,orasimplegeoquery.Inasimplequeryyoucanspecifyexactlyonecollectionandonecondition.Theresultcanthenbesortedandcanbesplitintopages.
WorkingwithSimplesQueriesusingHTTPTolimittheamountofresultstobetransferredinonebatch,simplequeriessupportabatchSizeparameterthatcanoptionallybeusedtotelltheservertolimitthenumberofresultstobetransferredinonebatchtoacertainvalue.Ifthequeryhasmoreresultsthanweretransferredinonego,moreresultsarewaitingontheserversotheycanbefetchedsubsequently.IfnovalueforthebatchSizeparameterisspecified,theserverwilluseareasonabledefaultvalue.
Iftheserverhasmoredocumentsthanshouldbereturnedinasinglebatch,theserverwillsetthehasMoreattributeintheresult.Itwillalsoreturntheidoftheserver-sidecursorintheidattributeintheresult.ThisidcanbeusedwiththecursorAPItofetchanyoutstandingresultsfromtheserveranddisposetheserver-sidecursorafterwards.
Returnalldocuments
returnsalldocumentsofacollection
PUT/_api/simple/all
RequestBody(required)
Containsthequery.
Returnsalldocumentsofacollections.ThecallexpectsaJSONobjectasbodywiththefollowingattributes:
collection:Thenameofthecollectiontoquery.
skip:Thenumberofdocumentstoskipinthequery(optional).
limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Example:Limittheamountofdocumentsusinglimit
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all<<EOF
{"collection":"products","skip":2,"limit":2}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12142",
"_id":"products/12142",
"_rev":"_WQ47fae--_",
"Hello1":"World1"
},
{
"_key":"12155",
SimpleQueries
204
"_id":"products/12155",
"_rev":"_WQ47fae--H",
"Hello5":"World5"
}
],
"hasMore":false,
"count":2,
"cached":false,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":4,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.00009989738464355469
},
"warnings":[]
},
"error":false,
"code":201
}
Example:UsingabatchSizevalue
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all<<EOF
{"collection":"products","batchSize":3}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":201,
"result":[
{
"_key":"12113",
"_id":"products/12113",
"_rev":"_WQ47fZ2--_",
"Hello1":"World1"
},
{
"_key":"12120",
"_id":"products/12120",
"_rev":"_WQ47fZ6--B",
"Hello3":"World3"
},
{
"_key":"12123",
"_id":"products/12123",
"_rev":"_WQ47fZ6--D",
"Hello4":"World4"
}
],
"hasMore":true,
"id":"12129",
"count":5,
"extra":{
"stats":{
"writesExecuted":0,
"writesIgnored":0,
"scannedFull":5,
"scannedIndex":0,
"filtered":0,
"httpRequests":0,
"executionTime":0.00010585784912109375
},
SimpleQueries
205
"warnings":[]
},
"cached":false
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Limittheamountofdocumentsusinglimit
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all<<EOF
{"collection":"products","skip":2,"limit":2}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingabatchSizevalue
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all<<EOF
{"collection":"products","batchSize":3}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Simplequeryby-example
returnsalldocumentsofacollectionmatchingagivenexample
PUT/_api/simple/by-example
AJSONobjectwiththesepropertiesisrequired:
skip:Thenumberofdocumentstoskipinthequery(optional).batchSize:maximumnumberofresultdocumentstobetransferredfromtheservertotheclientinoneroundtrip.Ifthisattributeisnotset,aserver-controlleddefaultvaluewillbeused.AbatchSizevalueof0isdisallowed.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)example:Theexampledocument.collection:Thenameofthecollectiontoquery.
Thiswillfindalldocumentsmatchingagivenexample.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Example:
SimpleQueries
206
Matchinganattribute
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example<<EOF
{
"collection":"products",
"example":{
"i":1
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12208",
"_id":"products/12208",
"_rev":"_WQ47fbm--_",
"a":{
"k":2,
"j":2
},
"i":1
},
{
"_key":"12202",
"_id":"products/12202",
"_rev":"_WQ47fbi--B",
"a":{
"j":1
},
"i":1
},
{
"_key":"12198",
"_id":"products/12198",
"_rev":"_WQ47fbi--_",
"a":{
"k":1,
"j":1
},
"i":1
},
{
"_key":"12205",
"_id":"products/12205",
"_rev":"_WQ47fbi--D",
"i":1
}
],
"hasMore":false,
"count":4,
"error":false,
"code":201
}
Example:Matchinganattributewhichisasub-document
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example<<EOF
{
"collection":"products",
"example":{
"a.j":1
}
}
EOF
SimpleQueries
207
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12228",
"_id":"products/12228",
"_rev":"_WQ47fcK--B",
"a":{
"j":1
},
"i":1
},
{
"_key":"12224",
"_id":"products/12224",
"_rev":"_WQ47fcK--_",
"a":{
"k":1,
"j":1
},
"i":1
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
Example:Matchinganattributewithinasub-document
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12254",
"_id":"products/12254",
"_rev":"_WQ47fcq--B",
"a":{
"j":1
},
"i":1
}
],
"hasMore":false,
"count":1,
"error":false,
"code":201
}
ReturnCodes
SimpleQueries
208
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Matchinganattribute
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example
<<EOF
{
"collection":"products",
"example":{
"i":1
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyMatchinganattributewhichisasub-document
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example
<<EOF
{
"collection":"products",
"example":{
"a.j":1
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyMatchinganattributewithinasub-document
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example
<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
}
}
EOF
SimpleQueries
209
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Finddocumentsmatchinganexample
returnsonedocumentofacollectionmatchingagivenexample
PUT/_api/simple/first-example
AJSONobjectwiththesepropertiesisrequired:
example:Theexampledocument.collection:Thenameofthecollectiontoquery.
Thiswillreturnthefirstdocumentmatchingagivenexample.
ReturnsaresultcontainingthedocumentorHTTP404ifnodocumentmatchedtheexample.
Ifmorethanonedocumentinthecollectionmatchesthespecifiedexample,onlyoneofthesedocumentswillbereturned,anditisundefinedwhichofthematchingdocumentsisreturned.
Example:Ifamatchingdocumentwasfound
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-example<<EOF
{
"collection":"products",
"example":{
"i":1
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"document":{
"_key":"12286",
"_id":"products/12286",
"_rev":"_WQ47fdO--F",
"a":{
"k":2,
"j":2
},
"i":1
},
"error":false,
"code":200
}
Example:Ifnodocumentwasfound
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-example<<EOF
{
SimpleQueries
210
"collection":"products",
"example":{
"l":1
}
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"code":404,
"errorNum":404,
"errorMessage":"nomatch"
}
ReturnCodes
200:isreturnedwhenthequerywassuccessfullyexecuted.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Ifamatchingdocumentwasfound
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-
example<<EOF
{
"collection":"products",
"example":{
"i":1
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyIfnodocumentwasfound
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-
example<<EOF
{
"collection":"products",
"example":{
"l":1
}
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
SimpleQueries
211
showresponsebody
Finddocumentsbytheirkeys
fetchesmultipledocumentsbytheirkeys
PUT/_api/simple/lookup-by-keys
AJSONobjectwiththesepropertiesisrequired:
keys(string):arraywiththe_keysofdocumentstoremove.collection:Thenameofthecollectiontolookinforthedocuments
Looksupthedocumentsinthespecifiedcollectionusingthearrayofkeysprovided.Alldocumentsforwhichamatchingkeywasspecifiedinthekeysarrayandthatexistinthecollectionwillbereturned.Keysforwhichnodocumentcanbefoundintheunderlyingcollectionareignored,andnoexceptionwillbethrownforthem.
ThebodyoftheresponsecontainsaJSONobjectwithadocumentsattribute.Thedocumentsattributeisanarraycontainingthematchingdocuments.Theorderinwhichmatchingdocumentsarepresentintheresultarrayisunspecified.
Example:Lookingupexistingdocuments
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/lookup-by-keys<<EOF
{
"keys":[
"test0",
"test1",
"test2",
"test3",
"test4",
"test5",
"test6",
"test7",
"test8",
"test9"
],
"collection":"test"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"documents":[
{
"_key":"test0",
"_id":"test/test0",
"_rev":"_WQ47ffG--_",
"value":0
},
{
"_key":"test1",
"_id":"test/test1",
"_rev":"_WQ47ffK--_",
"value":1
},
{
"_key":"test2",
"_id":"test/test2",
"_rev":"_WQ47ffK--B",
"value":2
},
{
"_key":"test3",
"_id":"test/test3",
"_rev":"_WQ47ffK--D",
SimpleQueries
212
"value":3
},
{
"_key":"test4",
"_id":"test/test4",
"_rev":"_WQ47ffK--F",
"value":4
},
{
"_key":"test5",
"_id":"test/test5",
"_rev":"_WQ47ffK--H",
"value":5
},
{
"_key":"test6",
"_id":"test/test6",
"_rev":"_WQ47ffK--J",
"value":6
},
{
"_key":"test7",
"_id":"test/test7",
"_rev":"_WQ47ffK--L",
"value":7
},
{
"_key":"test8",
"_id":"test/test8",
"_rev":"_WQ47ffK--N",
"value":8
},
{
"_key":"test9",
"_id":"test/test9",
"_rev":"_WQ47ffO--_",
"value":9
}
],
"error":false,
"code":200
}
Example:Lookingupnon-existingdocuments
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/lookup-by-keys<<EOF
{
"keys":[
"foo",
"bar",
"baz"
],
"collection":"test"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"documents":[],
"error":false,
"code":200
}
ReturnCodes
200:isreturnediftheoperationwascarriedoutsuccessfully.
SimpleQueries
213
404:isreturnedifthecollectionwasnotfound.Theresponsebodycontainsanerrordocumentinthiscase.405:isreturnediftheoperationwascalledwithadifferentHTTPMETHODthanPUT.
Examples
Lookingupexistingdocuments
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/lookup-by-
keys<<EOF
{
"keys":[
"test0",
"test1",
"test2",
"test3",
"test4",
"test5",
"test6",
"test7",
"test8",
"test9"
],
"collection":"test"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyLookingupnon-existingdocuments
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/lookup-by-
keys<<EOF
{
"keys":[
"foo",
"bar",
"baz"
],
"collection":"test"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Returnarandomdocument
returnsarandomdocumentfromacollection
SimpleQueries
214
PUT/_api/simple/any
Returnsarandomdocumentfromacollection.ThecallexpectsaJSONobjectasbodywiththefollowingattributes:
AJSONobjectwiththesepropertiesisrequired:
collection:Theidentifierornameofthecollectiontoquery.ReturnsaJSONobjectwiththedocumentstoredintheattributedocumentifthecollectioncontainsatleastonedocument.Ifthecollectionisempty,thedocumentattrbutecontainsnull.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/any<<EOF
{
"collection":"products"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"document":{
"_key":"12170",
"_id":"products/12170",
"_rev":"_WQ47fbC--_",
"Hello1":"World1"
},
"error":false,
"code":200
}
ReturnCodes
200:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/any<<EOF
{
"collection":"products"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Removedocumentsbytheirkeys
removesmultipledocumentsbytheirkeys
PUT/_api/simple/remove-by-keys
AJSONobjectwiththesepropertiesisrequired:
keys(string):arraywiththe_keysofdocumentstoremove.options:
SimpleQueries
215
returnOld:ifsettotrueandsilentaboveisfalse,thentheaboveinformationabouttheremoveddocumentscontainsthecompleteremoveddocuments.silent:ifsettofalse,thentheresultwillcontainanadditionalattributeoldwhichcontainsanarraywithoneentryforeachremoveddocument.Bydefault,theseentrieswillhavethe_id,_keyand_revattributes.waitForSync:ifsettotrue,thenallremovaloperationswillinstantlybesynchronizedtodisk.Ifthisisnotspecified,thenthecollection'sdefaultsyncbehaviorwillbeapplied.
collection:Thenameofthecollectiontolookinforthedocumentstoremove
Looksupthedocumentsinthespecifiedcollectionusingthearrayofkeysprovided,andremovesalldocumentsfromthecollectionwhosekeysarecontainedinthekeysarray.Keysforwhichnodocumentcanbefoundintheunderlyingcollectionareignored,andnoexceptionwillbethrownforthem.
ThebodyoftheresponsecontainsaJSONobjectwithinformationhowmanydocumentswereremoved(andhowmanywerenot).Theremovedattributewillcontainthenumberofactuallyremoveddocuments.Theignoredattributewillcontainthenumberofkeysintherequestforwhichnomatchingdocumentcouldbefound.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-keys<<EOF
{
"keys":[
"test0",
"test1",
"test2",
"test3",
"test4",
"test5",
"test6",
"test7",
"test8",
"test9"
],
"collection":"test"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"removed":10,
"ignored":0,
"error":false,
"code":200
}
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-keys<<EOF
{
"keys":[
"foo",
"bar",
"baz"
],
"collection":"test"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
SimpleQueries
216
"removed":0,
"ignored":3,
"error":false,
"code":200
}
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-
keys<<EOF
{
"keys":[
"test0",
"test1",
"test2",
"test3",
"test4",
"test5",
"test6",
"test7",
"test8",
"test9"
],
"collection":"test"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-
keys<<EOF
{
"keys":[
"foo",
"bar",
"baz"
],
"collection":"test"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Removedocumentsbyexample
removesalldocumentsofacollectionthatmatchanexample
PUT/_api/simple/remove-by-example
AJSONobjectwiththesepropertiesisrequired:
SimpleQueries
217
example:Anexampledocumentthatallcollectiondocumentsarecomparedagainst.collection:Thenameofthecollectiontoremovefrom.options:
limit:anoptionalvaluethatdetermineshowmanydocumentstodeleteatmost.Iflimitisspecifiedbutislessthanthenumberofdocumentsinthecollection,itisundefinedwhichofthedocumentswillbedeleted.waitForSync:ifsettotrue,thenallremovaloperationswillinstantlybesynchronizedtodisk.Ifthisisnotspecified,thenthecollection'sdefaultsyncbehaviorwillbeapplied.
Thiswillfindalldocumentsinthecollectionthatmatchthespecifiedexampleobject.
Note:thelimitattributeisnotsupportedonshardedcollections.Usingitwillresultinanerror.
Returnsthenumberofdocumentsthatweredeleted.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deleted":1,
"error":false,
"code":200
}
Example:UsingParameter:waitForSyncandlimit
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"waitForSync":true,
"limit":2
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deleted":1,
"error":false,
"code":200
}
SimpleQueries
218
Example:UsingParameter:waitForSyncandlimitwithnewsignature
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"options":{
"waitForSync":true,
"limit":2
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deleted":1,
"error":false,
"code":200
}
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-
example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingParameter:waitForSyncandlimit
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-
example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"waitForSync":true,
"limit":2
}
SimpleQueries
219
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingParameter:waitForSyncandlimitwithnewsignature
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-
example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"options":{
"waitForSync":true,
"limit":2
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Replacedocumentsbyexample
replacesthebodyofalldocumentsofacollectionthatmatchanexample
PUT/_api/simple/replace-by-example
AJSONobjectwiththesepropertiesisrequired:
options:limit:anoptionalvaluethatdetermineshowmanydocumentstoreplaceatmost.Iflimitisspecifiedbutislessthanthenumberofdocumentsinthecollection,itisundefinedwhichofthedocumentswillbereplaced.waitForSync:ifsettotrue,thenallremovaloperationswillinstantlybesynchronizedtodisk.Ifthisisnotspecified,thenthecollection'sdefaultsyncbehaviorwillbeapplied.
example:Anexampledocumentthatallcollectiondocumentsarecomparedagainst.collection:Thenameofthecollectiontoreplacewithin.newValue:Thereplacementdocumentthatwillgetinsertedinplaceofthe"old"documents.
Thiswillfindalldocumentsinthecollectionthatmatchthespecifiedexampleobject,andreplacetheentiredocumentbodywiththenewvaluespecified.Notethatdocumentmeta-attributessuchas_id,_key,_from,_toetc.cannotbereplaced.
Note:thelimitattributeisnotsupportedonshardedcollections.Usingitwillresultinanerror.
Returnsthenumberofdocumentsthatwerereplaced.
Example:
SimpleQueries
220
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/replace-by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"newValue":{
"foo":"bar"
},
"limit":3
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"replaced":1,
"error":false,
"code":200
}
Example:UsingnewSignatureforattributesWaitForSyncandlimit
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/replace-by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"newValue":{
"foo":"bar"
},
"options":{
"limit":3,
"waitForSync":true
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"replaced":1,
"error":false,
"code":200
}
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/replace-by-
example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
SimpleQueries
221
"newValue":{
"foo":"bar"
},
"limit":3
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingnewSignatureforattributesWaitForSyncandlimit
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/replace-by-
example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"newValue":{
"foo":"bar"
},
"options":{
"limit":3,
"waitForSync":true
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Updatedocumentsbyexample
partiallyupdatesthebodyofalldocumentsofacollectionthatmatchanexample
PUT/_api/simple/update-by-example
AJSONobjectwiththesepropertiesisrequired:
options:keepNull:Thisparametercanbeusedtomodifythebehaviorwhenhandlingnullvalues.Normally,nullvaluesarestoredinthedatabase.BysettingthekeepNullparametertofalse,thisbehaviorcanbechangedsothatallattributesindatawithnullvalueswillberemovedfromtheupdateddocument.mergeObjects:Controlswhetherobjects(notarrays)willbemergedifpresentinboththeexistingandthepatchdocument.Ifsettofalse,thevalueinthepatchdocumentwilloverwritetheexistingdocument'svalue.Ifsettotrue,objectswillbemerged.Thedefaultistrue.limit:anoptionalvaluethatdetermineshowmanydocumentstoupdateatmost.Iflimitisspecifiedbutislessthanthe
SimpleQueries
222
numberofdocumentsinthecollection,itisundefinedwhichofthedocumentswillbeupdated.waitForSync:ifsettotrue,thenallremovaloperationswillinstantlybesynchronizedtodisk.Ifthisisnotspecified,thenthecollection'sdefaultsyncbehaviorwillbeapplied.
example:Anexampledocumentthatallcollectiondocumentsarecomparedagainst.collection:Thenameofthecollectiontoupdatewithin.newValue:Adocumentcontainingalltheattributestoupdateinthefounddocuments.
Thiswillfindalldocumentsinthecollectionthatmatchthespecifiedexampleobject,andpartiallyupdatethedocumentbodywiththenewvaluespecified.Notethatdocumentmeta-attributessuchas_id,_key,_from,_toetc.cannotbereplaced.
Note:thelimitattributeisnotsupportedonshardedcollections.Usingitwillresultinanerror.
Returnsthenumberofdocumentsthatwereupdated.
Example:usingoldsyntaxforoptions
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/update-by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"newValue":{
"a":{
"j":22
}
},
"limit":3
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"updated":1,
"error":false,
"code":200
}
Example:usingnewsignatureforoptions
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/update-by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"newValue":{
"a":{
"j":22
}
},
"options":{
"limit":3,
"waitForSync":true
}
SimpleQueries
223
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"updated":1,
"error":false,
"code":200
}
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/update-by-
example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"newValue":{
"a":{
"j":22
}
},
"limit":3
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyusingnewsignatureforoptions
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/update-by-
example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
},
"newValue":{
"a":{
"j":22
}
},
"options":{
"limit":3,
"waitForSync":true
}
}
SimpleQueries
224
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Simplerangequery
returnsalldocumentsofacollectionwithinarange
PUT/_api/simple/range
AJSONobjectwiththesepropertiesisrequired:
right:Theupperbound.attribute:Theattributepathtocheck.collection:Thenameofthecollectiontoquery.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)closed:Iftrue,useintervalincludingleftandright,otherwiseexcluderight,butincludeleft.skip:Thenumberofdocumentstoskipinthequery(optional).left:Thelowerbound.
Thiswillfindalldocumentswithinagivenrange.Inordertoexecutearangequery,askip-listindexonthequeriedattributemustbepresent.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Note:therangesimplequeryisdeprecatedasofArangoDB2.6.ThefunctionmayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionwithinaspecificrangeistouseanAQLqueryasfollows:
FORdocIN@@collection
FILTERdoc.value>=@left&&doc.value<@right
LIMIT@skip,@limit
RETURNdoc`
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/range<<EOF
{
"collection":"products",
"attribute":"i",
"left":2,
"right":4
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12528",
"_id":"products/12528",
"_rev":"_WQ47fie--B",
"i":2
},
{
"_key":"12531",
"_id":"products/12531",
"_rev":"_WQ47fie--D",
SimpleQueries
225
"i":3
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknownornosuitableindexfortherangequeryispresent.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/range<<EOF
{
"collection":"products",
"attribute":"i",
"left":2,
"right":4
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Returnsdocumentsnearacoordinate
returnsalldocumentsofacollectionnearagivenlocation
PUT/_api/simple/near
AJSONobjectwiththesepropertiesisrequired:
distance:Ifgiven,theattributekeyusedtoreturnthedistancetothegivencoordinate.(optional).Ifspecified,distancesarereturnedinmeters.skip:Thenumberofdocumentstoskipinthequery.(optional)longitude:Thelongitudeofthecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)collection:Thenameofthecollectiontoquery.latitude:Thelatitudeofthecoordinate.geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)
Thedefaultwillfindatmost100documentsnearthegivencoordinate.Thereturnedarrayissortedaccordingtothedistance,withthenearestdocumentbeingfirstinthereturnarray.Ifthereareneardocumentsofequaldistance,documentsarechosenrandomlyfromthissetuntilthelimitisreached.
Inordertousethenearoperator,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
SimpleQueries
226
Note:thenearsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheNEARfunctionasfollows:
FORdocINNEAR(@@collection,@latitude,@longitude,@limit)
RETURNdoc`
Example:Withoutdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":2
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12441",
"_id":"products/12441",
"_rev":"_WQ47fgq--D",
"name":"Name/0.002/",
"loc":[
0.002,
0
]
},
{
"_key":"12435",
"_id":"products/12435",
"_rev":"_WQ47fgq--_",
"name":"Name/-0.002/",
"loc":[
-0.002,
0
]
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
Example:Withdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":3,
"distance":"distance"
}
SimpleQueries
227
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"distance":222.38985328911744,
"_id":"products/12486",
"_key":"12486",
"_rev":"_WQ47fhq--D",
"loc":[
-0.002,
0
],
"name":"Name/-0.002/"
},
{
"distance":222.38985328911744,
"_id":"products/12492",
"_key":"12492",
"_rev":"_WQ47fhq--H",
"loc":[
0.002,
0
],
"name":"Name/0.002/"
},
{
"distance":444.779706578235,
"_id":"products/12483",
"_key":"12483",
"_rev":"_WQ47fhq--B",
"loc":[
-0.004,
0
],
"name":"Name/-0.004/"
}
],
"hasMore":false,
"count":3,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Withoutdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":2
}
EOF
SimpleQueries
228
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyWithdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":3,
"distance":"distance"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Finddocumentswithinaradiusaroundacoordinate
returnsalldocumentsofacollectionwithinagivenradius
PUT/_api/simple/within
AJSONobjectwiththesepropertiesisrequired:
distance:Ifgiven,theattributekeyusedtoreturnthedistancetothegivencoordinate.(optional).Ifspecified,distancesarereturnedinmeters.skip:Thenumberofdocumentstoskipinthequery.(optional)longitude:Thelongitudeofthecoordinate.radius:Themaximalradius(inmeters).collection:Thenameofthecollectiontoquery.latitude:Thelatitudeofthecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)
Thiswillfindalldocumentswithinagivenradiusaroundthecoordinate(latitude,longitude).Thereturnedlistissortedbydistance.
Inordertousethewithinoperator,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Note:thewithinsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheWITHINfunctionasfollows:
FORdocINWITHIN(@@collection,@latitude,@longitude,@radius,@distanceAttributeName)
RETURNdoc
SimpleQueries
229
Example:Withoutdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":2,
"radius":500
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12854",
"_id":"products/12854",
"_rev":"_WQ47foi--_",
"name":"Name/0.002/",
"loc":[
0.002,
0
]
},
{
"_key":"12848",
"_id":"products/12848",
"_rev":"_WQ47foe--H",
"name":"Name/-0.002/",
"loc":[
-0.002,
0
]
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
Example:Withdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":3,
"distance":"distance",
"radius":300
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
SimpleQueries
230
{
"distance":222.38985328911744,
"_id":"products/12899",
"_key":"12899",
"_rev":"_WQ47fpW--B",
"loc":[
-0.002,
0
],
"name":"Name/-0.002/"
},
{
"distance":222.38985328911744,
"_id":"products/12905",
"_key":"12905",
"_rev":"_WQ47fpW--F",
"loc":[
0.002,
0
],
"name":"Name/0.002/"
},
{
"distance":444.779706578235,
"_id":"products/12896",
"_key":"12896",
"_rev":"_WQ47fpW--_",
"loc":[
-0.004,
0
],
"name":"Name/-0.004/"
}
],
"hasMore":false,
"count":3,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Withoutdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":2,
"radius":500
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
SimpleQueries
231
showresponsebodyWithdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":3,
"distance":"distance",
"radius":300
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Withinrectanglequery
returnsalldocumentsofacollectionwithinarectangle
PUT/_api/simple/within-rectangle
AJSONobjectwiththesepropertiesisrequired:
latitude1:Thelatitudeofthefirstrectanglecoordinate.skip:Thenumberofdocumentstoskipinthequery.(optional)latitude2:Thelatitudeofthesecondrectanglecoordinate.longitude2:Thelongitudeofthesecondrectanglecoordinate.longitude1:Thelongitudeofthefirstrectanglecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)collection:Thenameofthecollectiontoquery.geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)
Thiswillfindalldocumentswithinthespecifiedrectangle(determinedbythegivencoordinates(latitude1,longitude1,latitude2,longitude2).
Inordertousethewithin-rectanglequery,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/within-rectangle<<EOF
{
"collection":"products",
"latitude1":0,
"longitude1":0,
"latitude2":0.2,
"longitude2":0.2,
"skip":1,
"limit":2
}
EOF
SimpleQueries
232
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12965",
"_id":"products/12965",
"_rev":"_WQ47fqO--F",
"name":"Name/0.008/",
"loc":[
0.008,
0
]
},
{
"_key":"12962",
"_id":"products/12962",
"_rev":"_WQ47fqO--D",
"name":"Name/0.006/",
"loc":[
0.006,
0
]
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/within-
rectangle<<EOF
{
"collection":"products",
"latitude1":0,
"longitude1":0,
"latitude2":0.2,
"longitude2":0.2,
"skip":1,
"limit":2
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Fulltextindexquery
returnsdocumentsofacollectionasaresultofafulltextquery
SimpleQueries
233
PUT/_api/simple/fulltext
AJSONobjectwiththesepropertiesisrequired:
index:Theidentifierofthefulltext-indextouse.attribute:Theattributethatcontainsthetexts.collection:Thenameofthecollectiontoquery.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)skip:Thenumberofdocumentstoskipinthequery(optional).query:Thefulltextquery.PleaserefertoFulltextqueriesfordetails.
Thiswillfindalldocumentsfromthecollectionthatmatchthefulltextqueryspecifiedinquery.
Inordertousethefulltextoperator,afulltextindexmustbedefinedforthecollectionandthespecifiedattribute.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Note:thefulltextsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheFULLTEXTAQLfunctionasfollows:
FORdocINFULLTEXT(@@collection,@attributeName,@queryString,@limit)
RETURNdoc
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/fulltext<<EOF
{
"collection":"products",
"attribute":"text",
"query":"word"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12326",
"_id":"products/12326",
"_rev":"_WQ47feO--_",
"text":"thistextcontainsword"
},
{
"_key":"12330",
"_id":"products/12330",
"_rev":"_WQ47feS--_",
"text":"thistextalsohasaword"
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
SimpleQueries
234
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/fulltext
<<EOF
{
"collection":"products",
"attribute":"text",
"query":"word"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
SimpleQueries
235
HTTPInterfaceforAsyncResultsManagement
RequestExecution
ArangoDBprovidesvariousmethodsofexecutingclientrequests.Clientscanchoosetheappropriatemethodonaper-requestlevelbasedontheirthroughput,controlflow,anddurabilityrequirements.
Blockingexecution
ArangoDBisamulti-threadedserver,allowingtheprocessingofmultipleclientrequestsatthesametime.Communicationhandlingandtheactualworkcanbeperformedbymultipleworkerthreadsinparallel.
ThoughmultipleclientscanconnectandsendtheirrequestsinparalleltoArangoDB,clientsmayneedtowaitfortheirrequeststobeprocessed.
Bydefault,theserverwillfullyprocessanincomingrequestandthenreturntheresulttotheclient.Theclientmustwaitfortheserver'sresponsebeforeitcansendadditionalrequestsovertheconnection.Forclientsthataresingle-threadedornotevent-driven,waitingforthefullserverresponsemaybenon-optimal.
Furthermore,pleasenotethateveniftheclientclosestheHTTPconnection,therequestrunningontheserverwillstillcontinueuntilitiscompleteandonlythennoticethattheclientnolongerlistens.Thusclosingtheconnectiondoesnothelptoabortalongrunningquery!SeebelowunderAsyncExecutionandlaterResultRetrievalandHttpJobPutCancelfordetails.
FireandForget
Tomitigateclientblockingissues,ArangoDBsinceversion1.4.offersagenericmechanismfornon-blockingrequests:ifclientsaddtheHTTPheaderx-arango-async:truetotheirrequests,ArangoDBwillputtherequestintoanin-memorytaskqueueandreturnanHTTP202(accepted)responsetotheclientinstantly.Theserverwillexecutethetasksfromthequeueasynchronously,decouplingtheclientrequestsandtheactualwork.
Thisallowsformuchhigherthroughputthanifclientswouldwaitfortheserver'sresponse.Thedownsideisthattheresponsethatissenttotheclientisalwaysthesame(agenericHTTP202)andclientscannotmakeadecisionbasedontheactualoperation'sresultatthispoint.Infact,theoperationmighthavenotevenbeenexecutedatthetimethegenericresponsehasreachedtheclient.Clientscanthusnotrelyontheirrequestshavingbeenprocessedsuccessfully.
Theasynchronoustaskqueueontheserverisnotpersisted,meaningnot-yetprocessedtasksfromthequeuewillbelostincaseofacrash.However,theclientwillnotknowwhethertheywereprocessedornot.
Clientsshouldthusnotsendtheextraheaderwhentheyhavestrictdurabilityrequirementsoriftheyrelyonresultofthesentoperationforfurtheractions.
Themaximumnumberofqueuedtasksisdeterminedbythestartupoption-scheduler.maximal-queue-size.Ifmorethanthisnumberoftasksarealreadyqueued,theserverwillrejecttherequestwithanHTTP500error.
Finally,pleasenotethatitisnotpossibletocancelsuchafireandforgetjob,sinceyouwon'tgetanyhandletoidentifyitlateron.Ifyouneedtocancelrequests,useAsyncExecutionandlaterResultRetrievalandHttpJobPutCancelbelow.
AsyncExecutionandlaterResultRetrieval
ByaddingtheHTTPheaderx-arango-async:storetoarequest,clientscaninstructtheArangoDBservertoexecutetheoperationasynchronouslyasabove,butalsostoretheoperationresultinmemoryforalaterretrieval.TheserverwillreturnajobidintheHTTPresponseheaderx-arango-async-id.TheclientcanusethisidinconjunctionwiththeHTTPAPIat/_api/job,whichisdescribedindetailinthismanual.
ClientscanasktheArangoDBserverviatheasyncjobsAPIwhichresultsarereadyforretrieval,andwhicharenot.ClientscanalsousetheasyncjobsAPItoretrievetheoriginalresultsofanalreadyexecutedasyncjobbypassingittheoriginallyreturnedjobid.Theserverwillthenreturnthejobresultasifthejobwasexecutednormally.Furthermore,clientscancancelrunningasyncjobsbytheirjobid,seeHttpJobPutCancel.
AsyncResultHandling
236
ArangoDBwillkeepallresultsofjobsinitiatedwiththex-arango-async:storeheader.Resultsareremovedfromtheserveronlyifaclientexplicitlyaskstheserverforaspecificresult.
TheasyncjobsAPIalsoprovidesmethodsforgarbagecollectionthatclientscanusetogetridof"old"notfetchedresults.ClientsshouldcallthismethodperiodicallybecauseArangoDBdoesnotartificiallylimitthenumberofnot-yet-fetchedresults.
Itisthusaclientresponsibilitytostoreonlyasmanyresultsasneededandtofetchavailableresultsassoonaspossible,oratleasttocleanupnotfetchedresultsfromtimetotime.
Thejobqueueandtheresultsarekeptinmemoryonlyontheserver,sotheywillbelostincaseofacrash.
Cancelingasynchronousjobs
AsmentionedaboveitispossibletocancelanasynchronouslyrunningjobusingitsjobID.ThisisdonewithaPUTrequestasdescribedinHttpJobPutCancel.
However,afewwordsofexplanationaboutwhathappensbehindthescenesareinorder.Firstly,arunningasyncquerycaninternallybeexecutedbyC++codeorbyJavaScriptcode.ForexampleCRUDoperationsareexecuteddirectlyinC++,whereasAQLqueriesandtransactionsareexecutedbyJavaScriptcode.ThejobcancelationonlyworksforJavaScriptcode,sincethemechanismusedissimplytotriggeranuncatchableexceptionintheJavaScriptthread,whichwillbecaughtontheC++level,whichinturnleadstothecancelationofthejob.Noresultcanberetrievedlater,sincealldataabouttherequestisdiscarded.
Ifyoucancelajobrunningonacoordinatorofacluster(Sharding),thenonlythecoderunningonthecoordinatorisstopped,theremayremaintaskswithintheclusterwhichhavealreadybeendistributedtotheDBserversanditiscurrentlynotpossibletocancelthemaswell.
AsyncExecutionandAuthentication
Ifarequestrequiresauthentication,theauthenticationprocedureisrunbeforequeueing.Therequestwillonlybequeuedifitvalidcredentialsandtheauthenticationsucceeds.Iftherequestdoesnotcontainvalidcredentials,itwillnotbequeuedbutrejectedinstantlyinthesamewayasa"regular",non-queuedrequest.
ManagingAsyncResultsviaHTTP
Returnresultofanasyncjob
fetchesajobresultandremovesitfromthequeue
PUT/_api/job/{job-id}
PathParameters
job-id(required):Theasyncjobid.
Returnstheresultofanasyncjobidentifiedbyjob-id.Iftheasyncjobresultispresentontheserver,theresultwillberemovedfromthelistofresult.Thatmeansthismethodcanbecalledforeachjob-idonce.Themethodwillreturntheoriginaljobresult'sheadersandbody,plustheadditionalHTTPheaderx-arango-async-job-id.Ifthisheaderispresent,thenthejobwasfoundandtheresponsecontainstheoriginaljob'sresult.Iftheheaderisnotpresent,thejobwasnotfoundandtheresponsecontainsstatusinformationfromthejobmanager.
Example:Notprovidingajob-id:
shell>curl-XPUT--dump-http://localhost:8529/_api/job
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"badparameter",
AsyncResultHandling
237
"code":400,
"errorNum":400
}
Example:Providingajob-idforanon-existingjob:
shell>curl-XPUT--dump-http://localhost:8529/_api/job/notthere
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"notfound",
"code":404,
"errorNum":404
}
Example:FetchingtheresultofanHTTPGETjob:
shell>curl-XPUT--header'x-arango-async:store'--dump-http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883033
content-type:text/plain;charset=utf-8
shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759883033
HTTP/1.1200OK
x-content-type-options:nosniff
x-arango-async-id:151690759883033
content-type:application/json;charset=utf-8
{
"server":"arango",
"version":"3.3.3",
"license":"community"
}
Example:FetchingtheresultofanHTTPPOSTjobthatfailed:
shell>curl-XPUT--header'x-arango-async:store'--data-binary@---dump-http://localhost:8529/_api/collection<<EOF
{
"name":"thisnameisinvalid"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883038
content-type:text/plain;charset=utf-8
shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759883038
HTTP/1.1400BadRequest
x-content-type-options:nosniff
AsyncResultHandling
238
x-arango-async-id:151690759883038
content-type:application/json;charset=utf-8
{
"error":true,
"errorMessage":"expectedPUT/_api/collection/<collection-name>/<action>",
"code":400,
"errorNum":400
}
ReturnCodes
204:isreturnedifthejobrequestedviajob-idisstillinthequeueofpending(ornotyetfinished)jobs.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.400:isreturnedifnojob-idwasspecifiedintherequest.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.404:isreturnedifthejobwasnotfoundoralreadydeletedorfetchedfromthejobresultlist.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.
Examples
Notprovidingajob-id:
shell>curl-XPUT--dump-http://localhost:8529/_api/job
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyProvidingajob-idforanon-existingjob:
shell>curl-XPUT--dump-http://localhost:8529/_api/job/notthere
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyFetchingtheresultofanHTTPGETjob:
shell>curl-XPUT--header'x-arango-async:store'--dump-
http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883033
content-type:text/plain;charset=utf-8
shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759883033
HTTP/1.1200OK
x-content-type-options:nosniff
x-arango-async-id:151690759883033
content-type:application/json;charset=utf-8
showresponsebody
AsyncResultHandling
239
FetchingtheresultofanHTTPPOSTjobthatfailed:
shell>curl-XPUT--header'x-arango-async:store'--data-binary@---dump-
http://localhost:8529/_api/collection<<EOF
{
"name":"thisnameisinvalid"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883038
content-type:text/plain;charset=utf-8
shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759883038
HTTP/1.1400BadRequest
x-content-type-options:nosniff
x-arango-async-id:151690759883038
content-type:application/json;charset=utf-8
showresponsebody
Cancelasyncjob
cancelsanasyncjob
PUT/_api/job/{job-id}/cancel
PathParameters
job-id(required):Theasyncjobid.
Cancelsthecurrentlyrunningjobidentifiedbyjob-id.Notethatitstillmighttakesometimetoactuallycanceltherunningasyncjob.
Example:
shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF
{
"query":"FORiIN1..10FORjIN1..10LETx=sleep(1.0)FILTERi==5&&j==5RETURN42"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759882996
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/pending
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
"151690759882996"
]
shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759882996/cancel
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
AsyncResultHandling
240
{
"result":true
}
shell>curl--dump-http://localhost:8529/_api/job/pending
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
"151690759882996"
]
ReturnCodes
200:cancelhasbeeninitiated.400:isreturnedifnojob-idwasspecifiedintherequest.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.404:isreturnedifthejobwasnotfoundoralreadydeletedorfetchedfromthejobresultlist.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.
Examples
shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-
http://localhost:8529/_api/cursor<<EOF
{
"query":"FORiIN1..10FORjIN1..10LETx=sleep(1.0)FILTERi==5&&j==5
RETURN42"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759882996
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/pending
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
"151690759882996"
]
shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759882996/cancel
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Deletesasyncjob
deletesanasyncjobresult
DELETE/_api/job/{type}
PathParameters
AsyncResultHandling
241
type(required):Thetypeofjobstodelete.typecanbe:all:Deletesalljobsresults.Currentlyexecutingorqueuedasyncjobswillnotbestoppedbythiscall.expired:Deletesexpiredresults.Todeterminetheexpirationstatusofaresult,passthestampqueryparameter.stampneedstobeaUNIXtimestamp,andallasyncjobresultscreatedatalowertimestampwillbedeleted.anactualjob-id:Inthiscase,thecallwillremovetheresultofthespecifiedasyncjob.Ifthejobiscurrentlyexecutingorqueued,itwillnotbeaborted.
QueryParameters
stamp(optional):AUNIXtimestampspecifyingtheexpirationthresholdwhentypeisexpired.
Deleteseitheralljobresults,expiredjobresults,ortheresultofaspecificjob.Clientscanusethismethodtoperformaneventualgarbagecollectionofjobresults.
Example:Deletingalljobs:
shell>curl-XPUT--header'x-arango-async:store'--dump-http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883005
content-type:text/plain;charset=utf-8
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/all
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":true
}
Example:Deletingexpiredjobs:
shell>curl-XPUT--header'x-arango-async:store'--dump-http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883010
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_admin/time
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"time":1516907616.271038,
"error":false,
"code":200
}
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/expired?stamp=1516907616.271038
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":true
}
AsyncResultHandling
242
shell>curl--dump-http://localhost:8529/_api/job/pending
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[]
Example:Deletingtheresultofaspecificjob:
shell>curl-XPUT--header'x-arango-async:store'--dump-http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883019
content-type:text/plain;charset=utf-8
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/151690759883019
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":true
}
Example:Deletingtheresultofanon-existingjob:
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/AreYouThere
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"notfound",
"code":404,
"errorNum":404
}
ReturnCodes
200:isreturnedifthedeletionoperationwascarriedoutsuccessfully.Thiscodewillalsobereturnedifnoresultsweredeleted.400:isreturnediftypeisnotspecifiedorhasaninvalidvalue.404:isreturnediftypeisajob-idbutnoasyncjobwiththespecifiedidwasfound.
Examples
Deletingalljobs:
shell>curl-XPUT--header'x-arango-async:store'--dump-
http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883005
content-type:text/plain;charset=utf-8
AsyncResultHandling
243
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/all
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":true
}
Deletingexpiredjobs:
shell>curl-XPUT--header'x-arango-async:store'--dump-
http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883010
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_admin/time
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyDeletingtheresultofaspecificjob:
shell>curl-XPUT--header'x-arango-async:store'--dump-
http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883019
content-type:text/plain;charset=utf-8
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/151690759883019
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":true
}
Deletingtheresultofanon-existingjob:
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/AreYouThere
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
AsyncResultHandling
244
x-content-type-options:nosniff
showresponsebody
Returnsasyncjob
Returnsthestatusofaspecificjob
GET/_api/job/{job-id}
PathParameters
job-id(required):Theasyncjobid.
Returnstheprocessingstatusofthespecifiedjob.TheprocessingstatuscanbedeterminedbypeekingintotheHTTPresponsecodeoftheresponse.
Example:Queryingthestatusofadonejob:
shell>curl-XPUT--header'x-arango-async:store'--dump-http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883060
content-type:text/plain;charset=utf-8
shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759883060
HTTP/1.1200OK
x-content-type-options:nosniff
x-arango-async-id:151690759883060
content-type:application/json;charset=utf-8
{
"server":"arango",
"version":"3.3.3",
"license":"community"
}
Example:Queryingthestatusofapendingjob:(thereforewecreatealongrunngingjob...)
shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"read":[
"_frontend"
]
},
"action":"function(){require('internal').sleep(15.0);}"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883065
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/151690759883065
HTTP/1.1204NoContent
content-type:text/plain;charset=utf-8
AsyncResultHandling
245
x-content-type-options:nosniff
ReturnCodes
200:isreturnedifthejobrequestedviajob-idhasbeenexecutedanditsresultisreadytofetch.204:isreturnedifthejobrequestedviajob-idisstillinthequeueofpending(ornotyetfinished)jobs.404:isreturnedifthejobwasnotfoundoralreadydeletedorfetchedfromthejobresultlist.
Examples
Queryingthestatusofadonejob:
shell>curl-XPUT--header'x-arango-async:store'--dump-
http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883060
content-type:text/plain;charset=utf-8
shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759883060
HTTP/1.1200OK
x-content-type-options:nosniff
x-arango-async-id:151690759883060
content-type:application/json;charset=utf-8
showresponsebodyQueryingthestatusofapendingjob:(thereforewecreatealongrunngingjob...)
shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-
http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"read":[
"_frontend"
]
},
"action":"function(){require('internal').sleep(15.0);}"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883065
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/151690759883065
HTTP/1.1204NoContent
content-type:text/plain;charset=utf-8
x-content-type-options:nosniff
Returnslistofasyncjobs
AsyncResultHandling
246
Returnstheidsofjobresultswithaspecificstatus
GET/_api/job/{type}
PathParameters
type(required):Thetypeofjobstoreturn.Thetypecanbeeitherdoneorpending.Settingthetypetodonewillmakethemethodreturntheidsofalreadycompletedasyncjobsforwhichresultscanbefetched.Settingthetypetopendingwillreturntheidsofnotyetfinishedasyncjobs.
QueryParameters
count(optional):Themaximumnumberofidstoreturnpercall.Ifnotspecified,aserver-definedmaximumvaluewillbeused.
Returnsthelistofidsofasyncjobswithaspecificstatus(eitherdoneorpending).Thelistcanbeusedbytheclienttogetanoverviewofthejobsystemstatusandtoretrievecompletedjobresultslater.
Example:Fetchingthelistofdonejobs:
shell>curl-XPUT--header'x-arango-async:store'--dump-http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883043
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/done
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
"151690759883043"
]
Example:Fetchingthelistofpendingjobs:
shell>curl-XPUT--header'x-arango-async:store'--dump-http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883048
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/pending
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[]
Example:Queryingthestatusofapendingjob:(wecreateasleepjobtherefore...)
shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
AsyncResultHandling
247
"read":[
"_frontend"
]
},
"action":"function(){require('internal').sleep(15.0);}"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883053
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/pending
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
"151690759883053"
]
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/151690759883053
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":true
}
ReturnCodes
200:isreturnedifthelistcanbecompiledsuccessfully.Note:thelistmightbeempty.400:isreturnediftypeisnotspecifiedorhasaninvalidvalue.
Examples
Fetchingthelistofdonejobs:
shell>curl-XPUT--header'x-arango-async:store'--dump-
http://localhost:8529/_api/version
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883043
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/done
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
"151690759883043"
]
Fetchingthelistofpendingjobs:
shell>curl-XPUT--header'x-arango-async:store'--dump-
http://localhost:8529/_api/version
HTTP/1.1202Accepted
AsyncResultHandling
248
x-content-type-options:nosniff
x-arango-async-id:151690759883048
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/pending
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[]
Queryingthestatusofapendingjob:(wecreateasleepjobtherefore...)
shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-
http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"read":[
"_frontend"
]
},
"action":"function(){require('internal').sleep(15.0);}"
}
EOF
HTTP/1.1202Accepted
x-content-type-options:nosniff
x-arango-async-id:151690759883053
content-type:text/plain;charset=utf-8
shell>curl--dump-http://localhost:8529/_api/job/pending
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
"151690759883053"
]
shell>curl-XDELETE--dump-http://localhost:8529/_api/job/151690759883053
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":true
}
AsyncResultHandling
249
HTTPInterfaceforBulkImportsArangoDBprovidesanHTTPinterfacetoimportmultipledocumentsatonceintoacollection.Thisisknownasabulkimport.
ThedatauploadedmustbeprovidedinJSONformat.Therearetwomechanismstoimportthedata:
self-containedJSONdocuments:inthiscase,eachdocumentcontainsallattributenamesandvalues.Attributenamesmaybecompletelydifferentamongthedocumentsuploadedattributenamesplusdocumentdata:inthiscase,thefirstarraymustcontaintheattributenamesofthedocumentsthatfollow.Thefollowingarrayscontainingonlytheattributevalues.Attributevalueswillbemappedtotheattributenamesbypositions.
Theendpointaddressis/_api/importforbothinputmechanisms.DatamustbesenttothisURLusinganHTTPPOSTrequest.ThedatatoimportmustbecontainedinthebodyofthePOSTrequest.
Thecollectionqueryparametermustbeusedtospecifythetargetcollectionfortheimport.Importingdataintoanon-existingcollectionwillproduceanerror.
ThewaitForSyncqueryparametercanbesettotruetomaketheimportonlyreturnifalldocumentshavebeensyncedtodisk.
Thecompletequeryparametercanbesettotruetomaketheentireimportfailifanyoftheuploadeddocumentsisinvalidandcannotbeimported.Inthiscase,nodocumentswillbeimportedbytheimportrun,evenifafailurehappensattheendoftheimport.
Ifcompletehasavalueotherthantrue,validdocumentswillbeimportedwhileinvaliddocumentswillberejected,meaningonlysomeoftheuploadeddocumentsmighthavebeenimported.
ThedetailsqueryparametercanbesettotruetomaketheimportAPIreturndetailsaboutdocumentsthatcouldnotbeimported.Ifdetailsistrue,thentheresultwillalsocontainadetailsattributewhichisanarrayofdetailederrormessages.Ifthedetailsissettofalseoromitted,nodetailswillbereturned.
importsdocumentvalues
importsdocumentsfromJSON-encodedlists
POST/_api/import#document
RequestBody(required)
ThebodymustconsistofJSON-encodedarraysofattributevalues,withonelineperdocument.ThefirstrowoftherequestmustbeaJSON-encodedarrayofattributenames.Theseattributenamesareusedforthedatainthesubsequentlines.
QueryParameters
collection(required):Thecollectionname.fromPrefix(optional):Anoptionalprefixforthevaluesin_fromattributes.Ifspecified,thevalueisautomaticallyprependedtoeach_frominputvalue.Thisallowsspecifyingjustthekeysfor_from.toPrefix(optional):Anoptionalprefixforthevaluesin_toattributes.Ifspecified,thevalueisautomaticallyprependedtoeach_toinputvalue.Thisallowsspecifyingjustthekeysfor_to.overwrite(optional):Ifthisparameterhasavalueoftrueoryes,thenalldatainthecollectionwillberemovedpriortotheimport.Notethatanyexistingindexdefinitionswillbepreseved.waitForSync(optional):Waituntildocumentshavebeensyncedtodiskbeforereturning.onDuplicate(optional):Controlswhatactioniscarriedoutincaseofauniquekeyconstraintviolation.Possiblevaluesare:error:thiswillnotimportthecurrentdocumentbecauseoftheuniquekeyconstraintviolation.Thisisthedefaultsetting.update:thiswillupdateanexistingdocumentinthedatabasewiththedataspecifiedintherequest.Attributesoftheexistingdocumentthatarenotpresentintherequestwillbepreseved.replace:thiswillreplaceanexistingdocumentinthedatabasewiththedataspecifiedintherequest.ignore:thiswillnotupdateanexistingdocumentandsimplyignoretheerrorcausedbytheuniquekeyconstraintviolation.Notethatupdate,replaceandignorewillonlyworkwhentheimportdocumentintherequestcontainsthe_keyattribute.updateandreplacemayalsofailbecauseofsecondaryuniquekeyconstraintviolations.complete(optional):Ifsettotrueoryes,itwillmakethewholeimportfailifanyerroroccurs.Otherwisetheimportwillcontinueevenifsomedocumentscannotbeimported.details(optional):Ifsettotrueoryes,theresultwillincludeanattributedetailswithdetailsaboutdocumentsthatcouldnot
BulkImport/Export
250
beimported.
NOTESwaggerexampleswon'tworkduetotheanchor.
Createsdocumentsinthecollectionidentifiedbycollection-name.ThefirstlineoftherequestbodymustcontainaJSON-encodedarrayofattributenames.AllfollowinglinesintherequestbodymustcontainJSON-encodedarraysofattributevalues.Eachlineisinterpretedasaseparatedocument,andthevaluesspecifiedwillbemappedtothearrayofattributenamesspecifiedinthefirstheaderline.
TheresponseisaJSONobjectwiththefollowingattributes:
created:numberofdocumentsimported.
errors:numberofdocumentsthatwerenotimportedduetoanerror.
empty:numberofemptylinesfoundintheinput(willonlycontainavaluegreaterzerofortypesdocumentsorauto).
updated:numberofupdated/replaceddocuments(incaseonDuplicatewassettoeitherupdateorreplace).
ignored:numberoffailedbutignoredinsertoperations(incaseonDuplicatewassettoignore).
details:ifqueryparameterdetailsissettotrue,theresultwillcontainadetailsattributewhichisanarraywithmoredetailedinformationaboutwhichdocumentscouldnotbeinserted.
Example:Importingtwodocuments,withattributes_key,value1andvalue2each.Onelineintheimportdataisempty
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products<<EOF
["_key","value1","value2"]
["abc",25,"test"]
["foo","bar","baz"]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":2,
"errors":0,
"empty":1,
"updated":0,
"ignored":0
}
Example:Importingintoanedgecollection,withattributes_from,_toandname
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=links<<EOF
["_from","_to","name"]
["products/123","products/234","somename"]
["products/332","products/abc","othername"]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":2,
"errors":0,
"empty":0,
BulkImport/Export
251
"updated":0,
"ignored":0
}
Example:Importingintoanedgecollection,omitting_fromor_to
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=links&details=true<<EOF
["name"]
["somename"]
["othername"]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":0,
"errors":2,
"empty":0,
"updated":0,
"ignored":0,
"details":[
"atposition1:missing'_from'or'_to'attribute,offendingdocument:{\"name\":\"somename\"}",
"atposition2:missing'_from'or'_to'attribute,offendingdocument:{\"name\":\"othername\"}"
]
}
Example:Violatingauniqueconstraint,butallowpartialimports
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&details=true<<EOF
["_key","value1","value2"]
["abc",25,"test"]
["abc","bar","baz"]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":1,
"errors":1,
"empty":0,
"updated":0,
"ignored":0,
"details":[
"atposition1:creatingdocumentfailedwitherror'uniqueconstraintviolated',offendingdocument:{\"_key\":\"abc\",\"v
alue1\":\"bar\",\"value2\":\"baz\"}"
]
}
Example:Violatingauniqueconstraint,notallowingpartialimports
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&complete=true<<EOF
["_key","value1","value2"]
BulkImport/Export
252
["abc",25,"test"]
["abc","bar","baz"]
EOF
HTTP/1.1409Conflict
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"uniqueconstraintviolated",
"code":409,
"errorNum":1210
}
Example:Usinganon-existingcollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products<<EOF
["_key","value1","value2"]
["abc",25,"test"]
["foo","bar","baz"]
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"collectionnotfound:products",
"code":404,
"errorNum":1203
}
Example:Usingamalformedbody
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products<<EOF
{"_key":"foo","value1":"bar"}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"noJSONarrayfoundinsecondline",
"code":400,
"errorNum":400
}
ReturnCodes
201:isreturnedifalldocumentscouldbeimportedsuccessfully.400:isreturnediftypecontainsaninvalidvalue,nocollectionisspecified,thedocumentsareincorrectlyencoded,ortherequestismalformed.404:isreturnedifcollectionorthe_fromor_toattributesofanimportededgerefertoanunknowncollection.409:isreturnediftheimportwouldtriggerauniquekeyviolationandcompleteissettotrue.500:isreturnediftheservercannotauto-generateadocumentkey(outofkeyserror)foradocumentwithnouser-definedkey.
Examples
BulkImport/Export
253
Importingtwodocuments,withattributes_key,value1andvalue2each.Onelineintheimportdataisempty
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products<<EOF
["_key","value1","value2"]
["abc",25,"test"]
["foo","bar","baz"]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyImportingintoanedgecollection,withattributes_from,_toandname
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=links<<EOF
["_from","_to","name"]
["products/123","products/234","somename"]
["products/332","products/abc","othername"]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyImportingintoanedgecollection,omitting_fromor_to
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=links&details=true<<EOF
["name"]
["somename"]
["othername"]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyViolatingauniqueconstraint,butallowpartialimports
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&details=true<<EOF
["_key","value1","value2"]
["abc",25,"test"]
["abc","bar","baz"]
EOF
BulkImport/Export
254
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyViolatingauniqueconstraint,notallowingpartialimports
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&complete=true<<EOF
["_key","value1","value2"]
["abc",25,"test"]
["abc","bar","baz"]
EOF
HTTP/1.1409Conflict
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsinganon-existingcollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products<<EOF
["_key","value1","value2"]
["abc",25,"test"]
["foo","bar","baz"]
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingamalformedbody
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products<<EOF
{"_key":"foo","value1":"bar"}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
importsdocumentsfromJSON
importsdocumentsfromJSON
POST/_api/import#json
BulkImport/Export
255
RequestBody(required)
ThebodymusteitherbeaJSON-encodedarrayofobjectsorastringwithmultipleJSONobjectsseparatedbynewlines.
QueryParameters
type(required):Determineshowthebodyoftherequestwillbeinterpreted.typecanhavethefollowingvalues:documents:whenthistypeisused,eachlineintherequestbodyisexpectedtobeanindividualJSON-encodeddocument.MultipleJSONobjectsintherequestbodyneedtobeseparatedbynewlines.list:whenthistypeisused,therequestbodymustcontainasingleJSON-encodedarrayofindividualobjectstoimport.auto:ifset,thiswillautomaticallydeterminethebodytype(eitherdocumentsorlist).collection(required):Thecollectionname.fromPrefix(optional):Anoptionalprefixforthevaluesin_fromattributes.Ifspecified,thevalueisautomaticallyprependedtoeach_frominputvalue.Thisallowsspecifyingjustthekeysfor_from.toPrefix(optional):Anoptionalprefixforthevaluesin_toattributes.Ifspecified,thevalueisautomaticallyprependedtoeach_toinputvalue.Thisallowsspecifyingjustthekeysfor_to.overwrite(optional):Ifthisparameterhasavalueoftrueoryes,thenalldatainthecollectionwillberemovedpriortotheimport.Notethatanyexistingindexdefinitionswillbepreseved.waitForSync(optional):Waituntildocumentshavebeensyncedtodiskbeforereturning.onDuplicate(optional):Controlswhatactioniscarriedoutincaseofauniquekeyconstraintviolation.Possiblevaluesare:error:thiswillnotimportthecurrentdocumentbecauseoftheuniquekeyconstraintviolation.Thisisthedefaultsetting.update:thiswillupdateanexistingdocumentinthedatabasewiththedataspecifiedintherequest.Attributesoftheexistingdocumentthatarenotpresentintherequestwillbepreseved.replace:thiswillreplaceanexistingdocumentinthedatabasewiththedataspecifiedintherequest.ignore:thiswillnotupdateanexistingdocumentandsimplyignoretheerrorcausedbyauniquekeyconstraintviolation.Notethatthatupdate,replaceandignorewillonlyworkwhentheimportdocumentintherequestcontainsthe_keyattribute.updateandreplacemayalsofailbecauseofsecondaryuniquekeyconstraintviolations.complete(optional):Ifsettotrueoryes,itwillmakethewholeimportfailifanyerroroccurs.Otherwisetheimportwillcontinueevenifsomedocumentscannotbeimported.details(optional):Ifsettotrueoryes,theresultwillincludeanattributedetailswithdetailsaboutdocumentsthatcouldnotbeimported.
NOTESwaggerexampleswon'tworkduetotheanchor.
Createsdocumentsinthecollectionidentifiedbycollection-name.TheJSONrepresentationsofthedocumentsmustbepassedasthebodyofthePOSTrequest.Therequestbodycaneitherconsistofmultiplelines,witheachlinebeingasinglestand-aloneJSONobject,orasingeJSONarraywithsub-objects.
TheresponseisaJSONobjectwiththefollowingattributes:
created:numberofdocumentsimported.
errors:numberofdocumentsthatwerenotimportedduetoanerror.
empty:numberofemptylinesfoundintheinput(willonlycontainavaluegreaterzerofortypesdocumentsorauto).
updated:numberofupdated/replaceddocuments(incaseonDuplicatewassettoeitherupdateorreplace).
ignored:numberoffailedbutignoredinsertoperations(incaseonDuplicatewassettoignore).
details:ifqueryparameterdetailsissettotrue,theresultwillcontainadetailsattributewhichisanarraywithmoredetailedinformationaboutwhichdocumentscouldnotbeinserted.
Example:ImportingdocumentswithheterogenousattributesfromaJSONarray
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=list<<EOF
[
{
"_key":"abc",
"value1":25,
BulkImport/Export
256
"value2":"test",
"allowed":true
},
{
"_key":"foo",
"name":"baz"
},
{
"name":{
"detailed":"detailedname",
"short":"shortname"
}
}
]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":3,
"errors":0,
"empty":0,
"updated":0,
"ignored":0
}
Example:ImportingdocumentsfromindividualJSONlines
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=documents<<EOF
{"_key":"abc","value1":25,"value2":"test","allowed":true}
{"_key":"foo","name":"baz"}
{"name":{"detailed":"detailedname","short":"shortname"}}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":3,
"errors":0,
"empty":1,
"updated":0,
"ignored":0
}
Example:Usingtheautotypedetection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=auto<<EOF
[
{
"_key":"abc",
"value1":25,
"value2":"test",
"allowed":true
},
{
"_key":"foo",
BulkImport/Export
257
"name":"baz"
},
{
"name":{
"detailed":"detailedname",
"short":"shortname"
}
}
]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":3,
"errors":0,
"empty":0,
"updated":0,
"ignored":0
}
Example:Importingintoanedgecollection,withattributes_from,_toandname
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=links&type=documents<<EOF
{"_from":"products/123","_to":"products/234"}
{"_from":"products/332","_to":"products/abc","name":"othername"}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":2,
"errors":0,
"empty":0,
"updated":0,
"ignored":0
}
Example:Importingintoanedgecollection,omitting_fromor_to
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=links&type=list&details=true<<EOF
[
{
"name":"somename"
}
]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":0,
"errors":1,
"empty":0,
"updated":0,
BulkImport/Export
258
"ignored":0,
"details":[
"atposition1:missing'_from'or'_to'attribute,offendingdocument:{\"name\":\"somename\"}"
]
}
Example:Violatingauniqueconstraint,butallowpartialimports
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=documents&details=true
<<EOF
{"_key":"abc","value1":25,"value2":"test"}
{"_key":"abc","value1":"bar","value2":"baz"}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"created":1,
"errors":1,
"empty":0,
"updated":0,
"ignored":0,
"details":[
"atposition1:creatingdocumentfailedwitherror'uniqueconstraintviolated',offendingdocument:{\"_key\":\"abc\",\"v
alue1\":\"bar\",\"value2\":\"baz\"}"
]
}
Example:Violatingauniqueconstraint,notallowingpartialimports
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=documents&complete=tru
e<<EOF
{"_key":"abc","value1":25,"value2":"test"}
{"_key":"abc","value1":"bar","value2":"baz"}
EOF
HTTP/1.1409Conflict
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"uniqueconstraintviolated",
"code":409,
"errorNum":1210
}
Example:Usinganon-existingcollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=documents<<EOF
{"name":"test"}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
BulkImport/Export
259
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"collectionnotfound:products",
"code":404,
"errorNum":1203
}
Example:Usingamalformedbody
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=list<<EOF
{}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"expectingaJSONarrayintherequest",
"code":400,
"errorNum":400
}
ReturnCodes
201:isreturnedifalldocumentscouldbeimportedsuccessfully.400:isreturnediftypecontainsaninvalidvalue,nocollectionisspecified,thedocumentsareincorrectlyencoded,ortherequestismalformed.404:isreturnedifcollectionorthe_fromor_toattributesofanimportededgerefertoanunknowncollection.409:isreturnediftheimportwouldtriggerauniquekeyviolationandcompleteissettotrue.500:isreturnediftheservercannotauto-generateadocumentkey(outofkeyserror)foradocumentwithnouser-definedkey.
Examples
ImportingdocumentswithheterogenousattributesfromaJSONarray
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&type=list<<EOF
[
{
"_key":"abc",
"value1":25,
"value2":"test",
"allowed":true
},
{
"_key":"foo",
"name":"baz"
},
{
"name":{
"detailed":"detailedname",
"short":"shortname"
}
}
]
BulkImport/Export
260
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyImportingdocumentsfromindividualJSONlines
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&type=documents<<EOF
{"_key":"abc","value1":25,"value2":"test","allowed":true}
{"_key":"foo","name":"baz"}
{"name":{"detailed":"detailedname","short":"shortname"}}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingtheautotypedetection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&type=auto<<EOF
[
{
"_key":"abc",
"value1":25,
"value2":"test",
"allowed":true
},
{
"_key":"foo",
"name":"baz"
},
{
"name":{
"detailed":"detailedname",
"short":"shortname"
}
}
]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
BulkImport/Export
261
Importingintoanedgecollection,withattributes_from,_toandname
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=links&type=documents<<EOF
{"_from":"products/123","_to":"products/234"}
{"_from":"products/332","_to":"products/abc","name":"othername"}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyImportingintoanedgecollection,omitting_fromor_to
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=links&type=list&details=true<<EOF
[
{
"name":"somename"
}
]
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyViolatingauniqueconstraint,butallowpartialimports
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&type=documents&details=true<<EOF
{"_key":"abc","value1":25,"value2":"test"}
{"_key":"abc","value1":"bar","value2":"baz"}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyViolatingauniqueconstraint,notallowingpartialimports
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&type=documents&complete=true<<EOF
{"_key":"abc","value1":25,"value2":"test"}
{"_key":"abc","value1":"bar","value2":"baz"}
EOF
HTTP/1.1409Conflict
content-type:application/json;charset=utf-8
BulkImport/Export
262
x-content-type-options:nosniff
showresponsebodyUsinganon-existingcollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&type=documents<<EOF
{"name":"test"}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyUsingamalformedbody
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?
collection=products&type=list<<EOF
{}
EOF
HTTP/1.1400BadRequest
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
BulkImport/Export
263
ImportingSelf-ContainedJSONDocumentsThisimportmethodallowsuploadingself-containedJSONdocuments.ThedocumentsmustbeuploadedinthebodyoftheHTTPPOSTrequest.Eachlineofthebodywillbeinterpretedasonestand-alonedocument.Emptylinesinthebodyareallowedbutwillbeskipped.Usingthisformat,thedocumentsareimportedline-wise.
Exampleinputdata:{"_key":"key1",...}{"_key":"key2",...}...
Tousethismethod,thetypequeryparametershouldbesettodocuments.
Itisalsopossibletouploadself-containedJSONdocumentsthatareembeddedintoaJSONarray.Eachelementfromthearraywillbetreatedasadocumentandbeimported.
Exampleinputdataforthiscase:
[
{"_key":"key1",...},
{"_key":"key2",...},
...
]
Thisformatdoesnotrequireeachdocumenttobeonaseparateline,andanywhitespaceintheJSONdataisallowed.ItcanbeusedtoimportaJSON-formattedresultarray(e.g.fromarangosh)backintoArangoDB.UsingthisformatrequiresArangoDBtoparsethecompletearrayandkeepitinmemoryforthedurationoftheimport.Thismightbemoreresource-intensivethantheline-wiseprocessing.
Tousethismethod,thetypequeryparametershouldbesettoarray.
Settingthetypequeryparametertoautowillmaketheserverauto-detectwhetherthedataareline-wiseJSONdocuments(type=documents)oraJSONarray(type=array).
Examples
curl--data-binary@--XPOST--dump-"http://localhost:8529/_api/import?type=documents&collection=test"
{"name":"test","gender":"male","age":39}
{"type":"bird","name":"robin"}
HTTP/1.1201Created
Server:ArangoDB
Connection:Keep-Alive
Content-type:application/json;charset=utf-8
{"error":false,"created":2,"empty":0,"errors":0}
TheserverwillrespondwithanHTTP201ifeverythingwentwell.Thenumberofdocumentsimportedwillbereturnedinthecreatedattributeoftheresponse.Ifanydocumentswereskippedorincorrectlyformatted,thiswillbereturnedintheerrorsattribute.Therewillalsobeanattributeemptyintheresponse,whichwillcontainavalueof0.
Ifthedetailsparameterwassettotrueintherequest,theresponsewillalsocontainanattributedetailswhichisanarrayofdetailsabouterrorsthatoccurredontheserversideduringtheimport.Thisarraymightbeemptyifnoerrorsoccurred.
JSONDocuments
264
ImportingHeadersandValuesWhenusingthistypeofimport,theattributenamesofthedocumentstobeimportedarespecifiedseparatefromtheactualdocumentvaluedata.ThefirstlineoftheHTTPPOSTrequestbodymustbeaJSONarraycontainingtheattributenamesforthedocumentsthatfollow.Thefollowinglinesareinterpretedasthedocumentdata.EachdocumentmustbeaJSONarrayofvalues.Noattributenamesareneededorallowedinthisdatasection.
Examples
curl--data-binary@--XPOST--dump-"http://localhost:8529/_api/import?collection=test"
["firstName","lastName","age","gender"]
["Joe","Public",42,"male"]
["Jane","Doe",31,"female"]
HTTP/1.1201Created
Server:ArangoDB
Connection:Keep-Alive
Content-type:application/json;charset=utf-8
{"error":false,"created":2,"empty":0,"errors":0}
TheserverwillagainrespondwithanHTTP201ifeverythingwentwell.Thenumberofdocumentsimportedwillbereturnedinthecreatedattributeoftheresponse.Ifanydocumentswereskippedorincorrectlyformatted,thiswillbereturnedintheerrorsattribute.Thenumberofemptylinesintheinputfilewillbereturnedintheemptyattribute.
Ifthedetailsparameterwassettotrueintherequest,theresponsewillalsocontainanattributedetailswhichisanarrayofdetailsabouterrorsthatoccurredontheserversideduringtheimport.Thisarraymightbeemptyifnoerrorsoccurred.
ImportingintoEdgeCollections
Pleasenotethatwhenimportingdocumentsintoanedgecollection,itismandatorythatallimporteddocumentscontainthe_fromand_toattributes,andthatthesecontainreferencestoexistingcollections.
Headers&Values
265
HTTPInterfaceforBatchRequestsClientsnormallysendindividualoperationstoArangoDBinindividualHTTPrequests.Thisisstraightforwardandsimple,buthasthedisadvantagethatthenetworkoverheadcanbesignificantifmanysmallrequestsareissuedinarow.
Tomitigatethisproblem,ArangoDBoffersabatchrequestAPIthatclientscanusetosendmultipleoperationsinonebatchtoArangoDB.ThismethodisespeciallyusefulwhentheclienthastosendmanyHTTPrequestswithasmallbody/payloadandtheindividualrequestresultsdonotdependoneachother.
ClientscanuseArangoDB'sbatchAPIbyissuingamultipartHTTPPOSTrequesttotheURL/_api/batchhandler.ThehandlerwillaccepttherequestiftheContent-typeismultipart/form-dataandaboundarystringisspecified.ArangoDBwillthendecomposethebatchrequestintoitsindividualpartsusingthisboundary.Thisalsomeansthattheboundarystringitselfmustnotbecontainedinanyoftheparts.WhenArangoDBhassplitthemultipartrequestintoitsindividualparts,itwillprocessallpartssequentiallyasifitwereastandalonerequest.Whenallpartsareprocessed,ArangoDBwillgenerateamultipartHTTPresponsethatcontainsonepartforeachpartoperationresult.Forexample,ifyousendamultipartrequestwith5parts,ArangoDBwillsendbackamultipartresponsewith5partsaswell.
Theserverexpectseachpartmessagetostartwithexactlythefollowing"header":
Content-type:application/x-arango-batchpart
YoucanoptionallyspecifyaContent-Id"header"touniquelyidentifyeachpartmessage.TheserverwillreturntheContent-Idinitsresponseifitisspecified.Otherwise,theserverwillnotsendaContent-Id"header"back.TheserverwillnotvalidatetheuniquenessoftheContent-Id.AfterthemandatoryContent-typeandtheoptionalContent-Idheader,twoWindowslinebreaks(i.e.\r\n\r\n)mustfollow.Anydeviationofthisstructuremightleadtothepartbeingrejectedorincorrectlyinterpreted.Thepartrequestpayload,formattedasaregularHTTPrequest,mustfollowthetwoWindowslinebreaksliteraldirectly.
NotethattheliteralContent-type:application/x-arango-batchparttechnicallyistheheaderoftheMIMEpart,andtheHTTPrequest(includingitsheaders)isthebodypartoftheMIMEpart.
AnactualpartrequestshouldstartwiththeHTTPmethod,thecalledURL,andtheHTTPprotocolversionasusual,followedbyarbitraryHTTPheaders.Itsbodyshouldfollowaftertheusual\r\n\r\nliteral.PartrequestsarethereforeregularHTTPrequests,onlyembeddedinsideamultipartmessage.
Thefollowingexamplewillsendabatchwith3individualdocumentcreationoperations.TheboundaryusedinthisexampleisXXXsubpartXXX.
Examples
>curl-XPOST--data-binary@---header"Content-type:multipart/form-data;boundary=XXXsubpartXXX"http://localhost:8529/_api
/batch
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
Content-Id:1
POST/_api/document?collection=xyzHTTP/1.1
{"a":1,"b":2,"c":3}
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
Content-Id:2
POST/_api/document?collection=xyzHTTP/1.1
{"a":1,"b":2,"c":3,"d":4}
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
Content-Id:3
POST/_api/document?collection=xyzHTTP/1.1
{"a":1,"b":2,"c":3,"d":4,"e":5}
--XXXsubpartXXX--
BatchRequests
266
Theserverwillthenrespondwithonemultipartmessage,containingtheoverallstatusandtheindividualresultsforthepartoperations.Theoverallstatusshouldbe200excepttherewasanerrorwhileinspectingandprocessingthemultipartmessage.Theoverallstatusthereforedoesnotindicatethesuccessofeachpartoperation,butonlyindicateswhetherthemultipartmessagecouldbehandledsuccessfully.
Eachpartoperationwillreturnitsownstatusvalue.AsthepartoperationresultsareregularHTTPresponses(justincludedinonemultipartresponse),thepartoperationstatusisreturnedasaHTTPstatuscode.Thestatuscodesofthepartoperationsareexactlythesameasifyoucalledtheindividualoperationsstandalone.EachpartoperationmightalsoreturnarbitraryHTTPheadersandabody/payload:
Examples
HTTP/1.1200OK
Connection:Keep-Alive
Content-type:multipart/form-data;boundary=XXXsubpartXXX
Content-length:1055
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
Content-Id:1
HTTP/1.1202Accepted
Content-type:application/json;charset=utf-8
Etag:"9514299"
Content-length:53
{"error":false,"_id":"xyz/9514299","_key":"9514299","_rev":"9514299"}
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
Content-Id:2
HTTP/1.1202Accepted
Content-type:application/json;charset=utf-8
Etag:"9579835"
Content-length:53
{"error":false,"_id":"xyz/9579835","_key":"9579835","_rev":"9579835"}
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
Content-Id:3
HTTP/1.1202Accepted
Content-type:application/json;charset=utf-8
Etag:"9645371"
Content-length:53
{"error":false,"_id":"xyz/9645371","_key":"9645371","_rev":"9645371"}
--XXXsubpartXXX--
Intheaboveexample,theserverreturnedanoverallstatuscodeof200,andeachpartresponsecontainsitsownstatusvalue(202intheexample):
WhenconstructingthemultipartHTTPresponse,theserverwillusethesameboundarythattheclientsupplied.Ifanyofthepartresponseshasastatuscodeof400orgreater,theserverwillalsoreturnanHTTPheaderx-arango-errorscontainingtheoverallnumberofpartrequeststhatproducederrors:
Examples
>curl-XPOST--data-binary@---header"Content-type:multipart/form-data;boundary=XXXsubpartXXX"http://localhost:8529/_api
/batch
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
POST/_api/document?collection=nonexisting
{"a":1,"b":2,"c":3}
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
POST/_api/document?collection=xyz
BatchRequests
267
{"a":1,"b":2,"c":3,"d":4}
--XXXsubpartXXX--
Inthisexample,theoverallresponsecodeis200,butassomeofthepartrequestfailed(withstatuscode404),thex-arango-errorsheaderoftheoverallresponseis1:
Examples
HTTP/1.1200OK
x-arango-errors:1
Content-type:multipart/form-data;boundary=XXXsubpartXXX
Content-length:711
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
HTTP/1.1404NotFound
Content-type:application/json;charset=utf-8
Content-length:111
{"error":true,"code":404,"errorNum":1203,"errorMessage":"collection\/_api\/collection\/nonexistingnotfound"}
--XXXsubpartXXX
Content-type:application/x-arango-batchpart
HTTP/1.1202Accepted
Content-type:application/json;charset=utf-8
Etag:"9841979"
Content-length:53
{"error":false,"_id":"xyz/9841979","_key":"9841979","_rev":"9841979"}
--XXXsubpartXXX--
PleasenotethatthedatabaseusedforallpartoperationsofabatchrequestisdeterminedbyscanningtheoriginalURL(theURLthatcontains/_api/batch).Itisnotpossibletooverridethedatabasenameinpartoperationsofabatch.Whendoingso,anyotherdatabasenameusedinabatchpartwillbeignored.
executesabatchrequest
executesabatchrequest
POST/_api/batch
RequestBody(required)
Themultipartbatchrequest,consistingoftheenvelopeandtheindividualbatchparts.
Executesabatchrequest.AbatchrequestcancontainanynumberofotherrequeststhatcanbesenttoArangoDBinisolation.Thebenefitofusingbatchrequestsisthatbatchingrequestsrequireslessclient/serverroundtripsthanwhensendingisolatedrequests.
Allpartsofabatchrequestareexecutedseriallyontheserver.Theserverwillreturntheresultsofallpartsinasingleresponsewhenallpartsarefinished.
Technically,abatchrequestisamultipartHTTPrequest,withcontent-typemultipart/form-data.Abatchrequestconsistsofanenvelopeandtheindividualbatchpartactions.Batchpartactionsare"regular"HTTPrequests,includingfullheaderandanoptionalbody.Multiplebatchpartsareseparatedbyaboundaryidentifier.Theboundaryidentifierisdeclaredinthebatchenvelope.TheMIMEcontent-typeforeachindividualbatchpartmustbeapplication/x-arango-batchpart.
Pleasenotethatwhenconstructingtheindividualbatchparts,youmustuseCRLF(\\)asthelineterminatorasinregularHTTPmessages.
TheresponsesentbytheserverwillbeanHTTP200response,withanoptionalerrorsummaryheaderx-arango-errors.ThisheadercontainsthenumberofbatchpartoperationsthatfailedwithanHTTPerrorcodeofatleast400.Thisheaderisonlypresentintheresponseifthenumberoferrorsisgreaterthanzero.
Theresponsesentbytheserverisamultipartresponse,too.ItcontainstheindividualHTTPresponsesforallbatchparts,includingthefullHTTPresultheader(withstatuscodeandotherpotentialheaders)andanoptionalresultbody.Theindividualbatchpartsintheresultareseperatedusingthesameboundaryvalueasspecifiedintherequest.
BatchRequests
268
Theorderofbatchpartsintheresponsewillbethesameasintheoriginalclientrequest.ClientcanadditionallyusetheContent-IdMIMEheaderinabatchparttodefineanindividualidforeachbatchpart.Theserverwillreturnthisidisthebatchpartresponses,too.
Example:Sendingabatchrequestwithfivebatchparts:
GET/_api/version
DELETE/_api/collection/products
POST/_api/collection/products
GET/_api/collection/products/figures
DELETE/_api/collection/products
Theboundary(SomeBoundaryValue)ispassedtotheserverintheHTTPContent-TypeHTTPheader.Pleasenotethereplyisnotdisplayedallaccurate.
shell>curl-XPOST--header'Content-Type:multipart/form-data;boundary=SomeBoundaryValue'--data-binary@---dump-http://l
ocalhost:8529/_api/batch<<EOF
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:myId1
GET/_api/versionHTTP/1.1
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:myId2
DELETE/_api/collection/productsHTTP/1.1
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:someId
POST/_api/collection/productsHTTP/1.1
{"name":"products"}
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:nextId
GET/_api/collection/products/figuresHTTP/1.1
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:otherId
DELETE/_api/collection/productsHTTP/1.1
--SomeBoundaryValue--
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:multipart/form-data;boundary=SomeBoundaryValue
x-arango-errors:1
"--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:myId1
HTTP/1.1200OK
Server:
Connection:
Content-Type:application/json;charset=utf-8
Content-Length:59
BatchRequests
269
{\"server\":\"arango\",\"version\":\"3.3.3\",\"license\":\"community\"}
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:myId2
HTTP/1.1404NotFound
Server:
Connection:
Content-Type:application/json;charset=utf-8
Content-Length:79
{\"error\":true,\"errorMessage\":\"collectionnotfound\",\"code\":404,\"errorNum\":1203}
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:someId
HTTP/1.1200OK
Server:
Connection:
Content-Type:application/json;charset=utf-8
Content-Length:324
{\"code\":200,\"error\":false,\"status\":3,\"statusString\":\"loaded\",\"name\":\"products\",\"keyOptions\":{\"type\":\"traditi
onal\",\"allowUserKeys\":true,\"lastValue\":0},\"type\":2,\"indexBuckets\":8,\"globallyUniqueId\":\"h68719E5AC6E7/9990\",\"doCo
mpact\":true,\"waitForSync\":false,\"id\":\"9990\",\"isSystem\":false,\"journalSize\":33554432,\"isVolatile\":false}
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:nextId
HTTP/1.1200OK
Server:
Location:/_api/collection/products/figures
Connection:
Content-Type:application/json;charset=utf-8
Content-Length:831
{\"code\":200,\"error\":false,\"statusString\":\"loaded\",\"name\":\"products\",\"keyOptions\":{\"type\":\"traditional\",\"allo
wUserKeys\":true,\"lastValue\":0},\"journalSize\":33554432,\"isVolatile\":false,\"isSystem\":false,\"status\":3,\"count\":0,\"f
igures\":{\"indexes\":{\"count\":1,\"size\":32128},\"documentReferences\":0,\"waitingFor\":\"-\",\"alive\":{\"count\":0,\"size\
":0},\"dead\":{\"count\":0,\"size\":0,\"deletion\":0},\"compactionStatus\":{\"message\":\"compactionnotyetstarted\",\"time\"
:\"2018-01-25T19:13:37Z\",\"count\":0,\"filesCombined\":0,\"bytesRead\":0,\"bytesWritten\":0},\"datafiles\":{\"count\":0,\"file
Size\":0},\"journals\":{\"count\":0,\"fileSize\":0},\"compactors\":{\"count\":0,\"fileSize\":0},\"revisions\":{\"count\":0,\"si
ze\":48192},\"lastTick\":0,\"uncollectedLogfileEntries\":0},\"doCompact\":true,\"globallyUniqueId\":\"h68719E5AC6E7/9990\",\"ty
pe\":2,\"indexBuckets\":8,\"waitForSync\":false,\"id\":\"9990\"}
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:otherId
HTTP/1.1200OK
Server:
Connection:
Content-Type:application/json;charset=utf-8
Content-Length:38
{\"code\":200,\"error\":false,\"id\":\"9990\"}
--SomeBoundaryValue--"
Example:Sendingabatchrequest,settingtheboundaryimplicitly(theserverwillinthiscasetrytofindtheboundaryatthebeginningoftherequestbody).
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/batch<<EOF
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
DELETE/_api/collection/notexisting1HTTP/1.1
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
DELETE_api/collection/notexisting2HTTP/1.1
BatchRequests
270
--SomeBoundaryValue--
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:
x-arango-errors:2
"--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
HTTP/1.1404NotFound
Server:
Connection:
Content-Type:application/json;charset=utf-8
Content-Length:79
{\"error\":true,\"errorMessage\":\"collectionnotfound\",\"code\":404,\"errorNum\":1203}
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
HTTP/1.1404NotFound
Server:
Connection:
Content-Type:application/json;charset=utf-8
Content-Length:101
{\"error\":true,\"code\":404,\"errorNum\":404,\"errorMessage\":\"unknownpath'_api/collection/notexisting2'\"}
--SomeBoundaryValue--"
ReturnCodes
200:isreturnedifthebatchwasreceivedsuccessfully.HTTP200isreturnedevenifoneormultiplebatchpartactionsfailed.400:isreturnedifthebatchenvelopeismalformedorincorrectlyformatted.Thiscodewillalsobereturnedifthecontent-typeoftheoverallbatchrequestortheindividualMIMEpartsisnotasexpected.405:isreturnedwhenaninvalidHTTPmethodisused.
Examples
Sendingabatchrequestwithfivebatchparts:
GET/_api/versionDELETE/_api/collection/productsPOST/_api/collection/productsGET/_api/collection/products/figuresDELETE/_api/collection/productsTheboundary(SomeBoundaryValue)ispassedtotheserverintheHTTPContent-TypeHTTPheader.Pleasenotethereplyisnotdisplayedallaccurate.
shell>curl-XPOST--header'Content-Type:multipart/form-data;
boundary=SomeBoundaryValue'--data-binary@---dump-http://localhost:8529/_api/batch
<<EOF
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:myId1
GET/_api/versionHTTP/1.1
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:myId2
DELETE/_api/collection/productsHTTP/1.1
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:someId
BatchRequests
271
POST/_api/collection/productsHTTP/1.1
{"name":"products"}
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:nextId
GET/_api/collection/products/figuresHTTP/1.1
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
Content-Id:otherId
DELETE/_api/collection/productsHTTP/1.1
--SomeBoundaryValue--
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:multipart/form-data;boundary=SomeBoundaryValue
x-arango-errors:1
"--SomeBoundaryValue\r\nContent-Type:application/x-arango-batchpart\r\nContent-Id:
myId1\r\n\r\nHTTP/1.1200OK\r\nServer:\r\nConnection:\r\nContent-Type:
application/json;charset=utf-8\r\nContent-Length:
59\r\n\r\n{\"server\":\"arango\",\"version\":\"3.3.3\",\"license\":\"community\"}\r\n--
SomeBoundaryValue\r\nContent-Type:application/x-arango-batchpart\r\nContent-Id:
myId2\r\n\r\nHTTP/1.1404NotFound\r\nServer:\r\nConnection:\r\nContent-Type:
application/json;charset=utf-8\r\nContent-Length:
79\r\n\r\n{\"error\":true,\"errorMessage\":\"collectionnot
found\",\"code\":404,\"errorNum\":1203}\r\n--SomeBoundaryValue\r\nContent-Type:
application/x-arango-batchpart\r\nContent-Id:someId\r\n\r\nHTTP/1.1200OK\r\nServer:
\r\nConnection:\r\nContent-Type:application/json;charset=utf-8\r\nContent-Length:
324\r\n\r\n{\"code\":200,\"error\":false,\"status\":3,\"statusString\":\"loaded\",\"name\"
:\"products\",\"keyOptions\":
{\"type\":\"traditional\",\"allowUserKeys\":true,\"lastValue\":0},\"type\":2,\"indexBucket
s\":8,\"globallyUniqueId\":\"h68719E5AC6E7/9990\",\"doCompact\":true,\"waitForSync\":false
,\"id\":\"9990\",\"isSystem\":false,\"journalSize\":33554432,\"isVolatile\":false}\r\n--
SomeBoundaryValue\r\nContent-Type:application/x-arango-batchpart\r\nContent-Id:
nextId\r\n\r\nHTTP/1.1200OK\r\nServer:\r\nLocation:
/_api/collection/products/figures\r\nConnection:\r\nContent-Type:application/json;
charset=utf-8\r\nContent-Length:
831\r\n\r\n{\"code\":200,\"error\":false,\"statusString\":\"loaded\",\"name\":\"products\"
,\"keyOptions\":
{\"type\":\"traditional\",\"allowUserKeys\":true,\"lastValue\":0},\"journalSize\":33554432
,\"isVolatile\":false,\"isSystem\":false,\"status\":3,\"count\":0,\"figures\":
{\"indexes\":{\"count\":1,\"size\":32128},\"documentReferences\":0,\"waitingFor\":\"-
\",\"alive\":{\"count\":0,\"size\":0},\"dead\":
{\"count\":0,\"size\":0,\"deletion\":0},\"compactionStatus\":{\"message\":\"compactionnot
yetstarted\",\"time\":\"2018-01-
25T19:13:37Z\",\"count\":0,\"filesCombined\":0,\"bytesRead\":0,\"bytesWritten\":0},\"dataf
iles\":{\"count\":0,\"fileSize\":0},\"journals\":
{\"count\":0,\"fileSize\":0},\"compactors\":{\"count\":0,\"fileSize\":0},\"revisions\":
{\"count\":0,\"size\":48192},\"lastTick\":0,\"uncollectedLogfileEntries\":0},\"doCompact\"
:true,\"globallyUniqueId\":\"h68719E5AC6E7/9990\",\"type\":2,\"indexBuckets\":8,\"waitForS
ync\":false,\"id\":\"9990\"}\r\n--SomeBoundaryValue\r\nContent-Type:application/x-arango-
BatchRequests
272
batchpart\r\nContent-Id:otherId\r\n\r\nHTTP/1.1200OK\r\nServer:\r\nConnection:
\r\nContent-Type:application/json;charset=utf-8\r\nContent-Length:
38\r\n\r\n{\"code\":200,\"error\":false,\"id\":\"9990\"}\r\n--SomeBoundaryValue--"
Sendingabatchrequest,settingtheboundaryimplicitly(theserverwillinthiscasetrytofindtheboundaryatthebeginningoftherequestbody).
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/batch<<EOF
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
DELETE/_api/collection/notexisting1HTTP/1.1
--SomeBoundaryValue
Content-Type:application/x-arango-batchpart
DELETE_api/collection/notexisting2HTTP/1.1
--SomeBoundaryValue--
EOF
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:
x-arango-errors:2
"--SomeBoundaryValue\r\nContent-Type:application/x-arango-batchpart\r\n\r\nHTTP/1.1404
NotFound\r\nServer:\r\nConnection:\r\nContent-Type:application/json;charset=utf-
8\r\nContent-Length:79\r\n\r\n{\"error\":true,\"errorMessage\":\"collectionnot
found\",\"code\":404,\"errorNum\":1203}\r\n--SomeBoundaryValue\r\nContent-Type:
application/x-arango-batchpart\r\n\r\nHTTP/1.1404NotFound\r\nServer:\r\nConnection:
\r\nContent-Type:application/json;charset=utf-8\r\nContent-Length:
101\r\n\r\n{\"error\":true,\"code\":404,\"errorNum\":404,\"errorMessage\":\"unknownpath
'_api/collection/notexisting2'\"}\r\n--SomeBoundaryValue--"
BatchRequests
273
HTTPInterfaceforExportingDocuments
Createexportcursor
exportalldocumentsfromacollection,usingacursor
POST/_api/export
AJSONobjectwiththesepropertiesisrequired:
count:booleanflagthatindicateswhetherthenumberofdocumentsintheresultsetshouldbereturnedinthe"count"attributeoftheresult(optional).Calculatingthe"count"attributemightinthefuturehaveaperformanceimpactsothisoptionisturnedoffbydefault,and"count"isonlyreturnedwhenrequested.restrict:
fields(string):Containsanarrayofattributenamestoincludeorexclude.Matchingofattributenamesforinclusionorexclusionwillbedoneonthetoplevelonly.Specifyingnamesofnestedattributesisnotsupportedatthemoment.type:hastobebesettoeitherincludeorexcludedependingonwhichyouwanttouse
batchSize:maximumnumberofresultdocumentstobetransferredfromtheservertotheclientinoneroundtrip(optional).Ifthisattributeisnotset,aserver-controlleddefaultvaluewillbeused.flush:ifsettotrue,aWALflushoperationwillbeexecutedpriortotheexport.TheflushoperationwillstartcopyingdocumentsfromtheWALtothecollection'sdatafiles.TherewillbeanadditionalwaittimeofuptoflushWaitsecondsaftertheflushtoallowtheWALcollectortochangetheadjusteddocumentmeta-datatopointintothedatafiles,too.Thedefaultvalueisfalse(i.e.noflush)somostrecentlyinsertedorupdateddocumentsfromthecollectionmightbemissingintheexport.flushWait:maximumwaittimeinsecondsafteraflushoperation.Thedefaultvalueis10.Thisoptiononlyhasaneffectwhenflushissettotrue.limit:anoptionallimitvalue,determiningthemaximumnumberofdocumentstobeincludedinthecursor.Omittingthelimitattributeorsettingitto0willleadtonolimitbeingused.Ifalimitisused,itisundefinedwhichdocumentsfromthecollectionwillbeincludedintheexportandwhichwillbeexcluded.Thisisbecausethereisnonaturalorderofdocumentsinacollection.ttl:anoptionaltime-to-liveforthecursor(inseconds).Thecursorwillberemovedontheserverautomaticallyafterthespecifiedamountoftime.Thisisusefultoensuregarbagecollectionofcursorsthatarenotfullyfetchedbyclients.Ifnotset,aserver-definedvaluewillbeused.
Acalltothismethodcreatesacursorcontainingalldocumentsinthespecifiedcollection.Incontrasttootherdata-producingAPIs,theinternaldatastructuresproducedbytheexportAPIaremorelightweight,soitisthepreferredwaytoretrievealldocumentsfromacollection.
Documentsarereturnedinasimilarmannerasinthe/_api/cursorRESTAPI.Ifalldocumentsofthecollectionfitintothefirstbatch,thennocursorwillbecreated,andtheresultobject'shasMoreattributewillbesettofalse.Ifnotalldocumentsfitintothefirstbatch,thentheresultobject'shasMoreattributewillbesettotrue,andtheidattributeoftheresultwillcontainacursorid.
Theorderinwhichthedocumentsarereturnedisnotspecified.
Bydefault,onlythosedocumentsfromthecollectionwillbereturnedthatarestoredinthecollection'sdatafiles.Documentsthatarepresentinthewrite-aheadlog(WAL)atthetimetheexportisrunwillnotbeexported.
Toexportthesedocumentsaswell,thecallercanissueaWALflushrequestbeforecallingtheexportAPIorsettheflushattribute.SettingtheflushoptionwilltriggeraWALflushbeforetheexportsodocumentsgetcopiedfromtheWALtothecollectiondatafiles.
Iftheresultsetcanbecreatedbytheserver,theserverwillrespondwithHTTP201.ThebodyoftheresponsewillcontainaJSONobjectwiththeresultset.
ThereturnedJSONobjecthasthefollowingproperties:
error:booleanflagtoindicatethatanerroroccurred(falseinthiscase)
code:theHTTPstatuscode
result:anarrayofresultdocuments(mightbeemptyifthecollectionwasempty)
hasMore:abooleanindicatorwhethertherearemoreresultsavailableforthecursorontheserver
count:thetotalnumberofresultdocumentsavailable(onlyavailableifthequerywasexecutedwiththecountattributeset)
Exportingdata
274
id:idoftemporarycursorcreatedontheserver(optional,seeabove)
IftheJSONrepresentationismalformedorthequeryspecificationismissingfromtherequest,theserverwillrespondwithHTTP400.
ThebodyoftheresponsewillcontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:
error:booleanflagtoindicatethatanerroroccurred(trueinthiscase)
code:theHTTPstatuscode
errorNum:theservererrornumber
errorMessage:adescriptiveerrormessage
Clientsshouldalwaysdeleteanexportcursorresultasearlyaspossiblebecausealingeringexportcursorwillpreventtheunderlyingcollectionfrombeingcompactedorunloaded.Bydefault,unusedcursorswillbedeletedautomaticallyafteraserver-definedidletime,andclientscanadjustthisidletimebysettingthettlvalue.
Note:thisAPIiscurrentlynotsupportedonclustercoordinators.
Exportingdata
275
HTTPInterfaceforIndexes
Indexes
ThisisanintroductiontoArangoDB'sHTTPinterfaceforindexesingeneral.Therearespecialsectionsforvariousindextypes.
Index
Indexesareusedtoallowfastaccesstodocuments.Foreachcollectionthereisalwaystheprimaryindexwhichisahashindexforthedocumentkey(_keyattribute).Thisindexcannotbedroppedorchanged.edgecollectionswillalsohaveanautomaticallycreatededgesindex,whichcannotbemodified.Thisindexprovidesquickaccesstodocumentsviathe_fromand_toattributes.
Mostuser-landindexescanbecreatedbydefiningthenamesoftheattributeswhichshouldbeindexed.Someindextypesallowindexingjustoneattribute(e.g.fulltextindex)whereasotherindextypesallowindexingmultipleattributes.
Usingthesystemattribute_idinuser-definedindexesisnotsupportedbyanyindextype.
IndexHandle
Anindexhandleuniquelyidentifiesanindexinthedatabase.Itisastringandconsistsofacollectionnameandanindexidentifierseparatedby/.GeoIndex:Ageoindexisusedtofindplacesonthesurfaceoftheearthfast.HashIndex:Ahashindexisusedtofinddocumentsbasedonexamples.Ahashindexcanbecreatedforoneormultipledocumentattributes.Ahashindexwillonlybeusedbyqueriesifallindexedattributesarepresentintheexampleorsearchquery,andifallattributesarecomparedusingtheequality(==operator).Thatmeansthehashindexdoesnotsupportrangequeries.
Iftheindexisdeclaredunique,thenaccesstotheindexedattributesshouldbefast.Theperformancedegradesiftheindexedattribute(s)contain(s)onlyveryfewdistinctvalues.
EdgesIndex
Anedgesindexisautomaticallycreatedforedgecollections.Itcontainsconnectionsbetweenvertexdocumentsandisinvokedwhentheconnectingedgesofavertexarequeried.Thereisnowaytoexplicitlycreateordeleteedgeindexes.
SkiplistIndex
Askiplistisasortedindexthatcanbeusedtofindindividualdocumentsorrangesofdocuments.
PersistentIndex
Apersistentindexisasortedindexthatcanbeusedforfindingindividualdocumentsorrangesofdocuments.Inconstrasttotheotherindexes,thecontentsofapersistentindexarestoredondiskandthusdonotneedtoberebuiltinmemoryfromthedocumentswhenthecollectionisloaded.
FulltextIndex:
Afulltextindexcanbeusedtofindwords,orprefixesofwordsinsidedocuments.Afulltextindexcanbesetononeattributeonly,andwillindexallwordscontainedindocumentsthathaveatextualvalueinthisattribute.Onlywordswitha(specifiable)minimumlengthareindexed.Wordtokenizationisdoneusingthewordboundaryanalysisprovidedbylibicu,whichistakingintoaccounttheselectedlanguageprovidedatserverstart.Wordsareindexedintheirlower-casedform.Theindexsupportscompletematchqueries(fullwords)andprefixqueries.
Thebasicoperations(create,read,update,delete)fordocumentsaremappedtothestandardHTTPmethods(POST,GET,PUT,DELETE).
AddressofanIndex
Indexes
276
AllindexesinArangoDBhaveanuniquehandle.ThisindexhandleidentifiesanindexandismanagedbyArangoDB.AllindexesarefoundundertheURI
http://server:port/_api/index/index-handle
Forexample:Assumethattheindexhandleisdemo/63563528thentheURLofthatindexis:
http://localhost:8529/_api/index/demo/63563528
Indexes
277
WorkingwithIndexesusingHTTP
Readindex
returnsanindex
GET/_api/index/{index-handle}
PathParameters
index-handle(required):Theindex-handle.
Theresultisanobjectdescribingtheindex.Ithasatleastthefollowingattributes:
id:theidentifieroftheindex
type:theindextype
Allotherattributesaretype-dependent.Forexample,someindexesprovideuniqueorsparseflags,whereasothersdon't.SomeindexesalsoprovideaselectivityestimateintheselectivityEstimateattributeoftheresult.
Example:
shell>curl--dump-http://localhost:8529/_api/index/products/0
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"fields":[
"_key"
],
"id":"products/0",
"selectivityEstimate":1,
"sparse":false,
"type":"primary",
"unique":true,
"error":false,
"code":200
}
ReturnCodes
200:Iftheindexexists,thenaHTTP200isreturned.404:Iftheindexdoesnotexist,thenaHTTP404isreturned.
Examples
shell>curl--dump-http://localhost:8529/_api/index/products/0
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Createindex
createsanindex
WorkingwithIndexes
278
POST/_api/index#general
QueryParameters
collection(required):Thecollectionname.
RequestBody(required)
NOTESwaggerexampleswon'tworkduetotheanchor.
Createsanewindexinthecollectioncollection.Expectsanobjectcontainingtheindexdetails.
Thetypeoftheindextobecreatedmustspecifiedinthetypeattributeoftheindexdetails.Dependingontheindextype,additionalotherattributesmayneedtospecifiedintherequestinordertocreatetheindex.
Indexesrequirethetobeindexedattribute(s)inthefieldsattributeoftheindexdetails.Dependingontheindextype,asingleattributeormultipleattributescanbeindexed.Inthelattercase,anarrayofstringsisexpected.
Indexingthesystemattribute_idisnotsupportedforuser-definedindexes.Manuallycreatinganindexusing_idasanindexattributewillfailwithanerror.
Someindexescanbecreatedasuniqueornon-uniquevariants.Uniquenesscanbecontrolledformostindexesbyspecifyingtheuniqueflagintheindexdetails.Settingittotruewillcreateauniqueindex.Settingittofalseoromittingtheuniqueattributewillcreateanon-uniqueindex.
Note:Thefollowingindextypesdonotsupportuniqueness,andusingtheuniqueattributewiththesetypesmayleadtoanerror:
geoindexesfulltextindexes
Note:Uniqueindexesonnon-shardkeysarenotsupportedinacluster.
Hash,skiplistandpersistentindexescanoptionallybecreatedinasparsevariant.Asparseindexwillbecreatedifthesparseattributeintheindexdetailsissettotrue.Sparseindexesdonotindexdocumentsforwhichanyoftheindexattributesiseithernotsetorisnull.
Theoptionalattributededuplicateissupportedbyarrayindexesoftypehashorskiplist.Itcontrolswhetherinsertingduplicateindexvaluesfromthesamedocumentintoauniquearrayindexwillleadtoauniqueconstrainterrorornot.Thedefaultvalueistrue,soonlyasingleinstanceofeachnon-uniqueindexvaluewillbeinsertedintotheindexperdocument.Tryingtoinsertavalueintotheindexthatalreadyexistsintheindexwillalwaysfail,regardlessofthevalueofthisattribute.
ReturnCodes
200:Iftheindexalreadyexists,thenanHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenanHTTP201isreturned.400:Ifaninvalidindexdescriptionispostedorattributesareusedthatthetargetindexwillnotsupport,thenanHTTP400isreturned.404:Ifcollectionisunknown,thenanHTTP404isreturned.
Deleteindex
deletesanindex
DELETE/_api/index/{index-handle}
PathParameters
index-handle(required):Theindexhandle.
Deletesanindexwithindex-handle.
Example:
shell>curl-XDELETE--dump-http://localhost:8529/_api/index/products/11938
HTTP/1.1200OK
content-type:application/json;charset=utf-8
WorkingwithIndexes
279
x-content-type-options:nosniff
{
"id":"products/11938",
"error":false,
"code":200
}
ReturnCodes
200:Iftheindexcouldbedeleted,thenanHTTP200isreturned.404:Iftheindex-handleisunknown,thenanHTTP404isreturned.
Examples
shell>curl-XDELETE--dump-http://localhost:8529/_api/index/products/11938
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Readallindexesofacollection
returnsallindexesofacollection
GET/_api/index
QueryParameters
collection(required):Thecollectionname.
Returnsanobjectwithanattributeindexescontaininganarrayofallindexdescriptionsforthegivencollection.Thesameinformationisalsoavailableintheidentifiersasanobjectwiththeindexhandlesaskeys.
Example:Returninformationaboutallindexes
shell>curl--dump-http://localhost:8529/_api/index?collection=products
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"indexes":[
{
"fields":[
"_key"
],
"id":"products/0",
"selectivityEstimate":1,
"sparse":false,
"type":"primary",
"unique":true
},
{
"deduplicate":true,
"fields":[
"name"
],
WorkingwithIndexes
280
"id":"products/11780",
"selectivityEstimate":1,
"sparse":false,
"type":"hash",
"unique":false
},
{
"deduplicate":true,
"fields":[
"price"
],
"id":"products/11783",
"sparse":true,
"type":"skiplist",
"unique":false
}
],
"identifiers":{
"products/0":{
"fields":[
"_key"
],
"id":"products/0",
"selectivityEstimate":1,
"sparse":false,
"type":"primary",
"unique":true
},
"products/11780":{
"deduplicate":true,
"fields":[
"name"
],
"id":"products/11780",
"selectivityEstimate":1,
"sparse":false,
"type":"hash",
"unique":false
},
"products/11783":{
"deduplicate":true,
"fields":[
"price"
],
"id":"products/11783",
"sparse":true,
"type":"skiplist",
"unique":false
}
}
}
ReturnCodes
200:returnsaJSONobjectcontainingalistofindexesonthatcollection.
Examples
Returninformationaboutallindexes
shell>curl--dump-http://localhost:8529/_api/index?collection=products
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
WorkingwithIndexes
281
WorkingwithHashIndexesIfasuitablehashindexexists,then/_api/simple/by-examplewillusethisindextoexecuteaquery-by-example.
Createhashindex
createsahashindex
POST/_api/index#hash
QueryParameters
collection-name(required):Thecollectionname.
AJSONobjectwiththesepropertiesisrequired:
fields(string):anarrayofattributepaths.unique:iftrue,thencreateauniqueindex.type:mustbeequalto"hash" .sparse:iftrue,thencreateasparseindex.deduplicate:iffalse,thededuplicationofarrayvaluesisturnedoff.
NOTESwaggerexampleswon'tworkduetotheanchor.
Createsahashindexforthecollectioncollection-nameifitdoesnotalreadyexist.Thecallexpectsanobjectcontainingtheindexdetails.
Inasparseindexalldocumentswillbeexcludedfromtheindexthatdonotcontainatleastoneofthespecifiedindexattributes(i.e.fields)orthathaveavalueofnullinanyofthespecifiedindexattributes.Suchdocumentswillnotbeindexed,andnotbetakenintoaccountforuniquenesschecksiftheuniqueflagisset.
Inanon-sparseindex,thesedocumentswillbeindexed(fornon-presentindexedattributes,avalueofnullwillbeused)andwillbetakenintoaccountforuniquenesschecksiftheuniqueflagisset.
Note:uniqueindexesonnon-shardkeysarenotsupportedinacluster.
Example:Creatinganuniqueconstraint
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"hash",
"unique":true,
"fields":[
"a",
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deduplicate":true,
"fields":[
"a",
"b"
],
"id":"products/11882",
"isNewlyCreated":true,
"selectivityEstimate":1,
"sparse":false,
"type":"hash",
Hash
282
"unique":true,
"error":false,
"code":201
}
Example:Creatinganon-uniquehashindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"hash",
"unique":false,
"fields":[
"a",
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deduplicate":true,
"fields":[
"a",
"b"
],
"id":"products/11840",
"isNewlyCreated":true,
"selectivityEstimate":1,
"sparse":false,
"type":"hash",
"unique":false,
"error":false,
"code":201
}
Example:Creatingasparseindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"hash",
"unique":false,
"sparse":true,
"fields":[
"a"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deduplicate":true,
"fields":[
"a"
],
"id":"products/11896",
"isNewlyCreated":true,
"selectivityEstimate":1,
"sparse":true,
Hash
283
"type":"hash",
"unique":false,
"error":false,
"code":201
}
ReturnCodes
200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.400:Ifthecollectionalreadycontainsdocumentsandyoutrytocreateauniquehashindexinsuchawaythattherearedocumentsviolatingtheuniqueness,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Creatinganuniqueconstraint
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"hash",
"unique":true,
"fields":[
"a",
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyCreatinganon-uniquehashindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"hash",
"unique":false,
"fields":[
"a",
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyCreatingasparseindex
Hash
284
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"hash",
"unique":false,
"sparse":true,
"fields":[
"a"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Simplequeryby-example
returnsalldocumentsofacollectionmatchingagivenexample
PUT/_api/simple/by-example
AJSONobjectwiththesepropertiesisrequired:
skip:Thenumberofdocumentstoskipinthequery(optional).batchSize:maximumnumberofresultdocumentstobetransferredfromtheservertotheclientinoneroundtrip.Ifthisattributeisnotset,aserver-controlleddefaultvaluewillbeused.AbatchSizevalueof0isdisallowed.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)example:Theexampledocument.collection:Thenameofthecollectiontoquery.
Thiswillfindalldocumentsmatchingagivenexample.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Example:Matchinganattribute
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example<<EOF
{
"collection":"products",
"example":{
"i":1
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12208",
"_id":"products/12208",
"_rev":"_WQ47fbm--_",
"a":{
"k":2,
Hash
285
"j":2
},
"i":1
},
{
"_key":"12202",
"_id":"products/12202",
"_rev":"_WQ47fbi--B",
"a":{
"j":1
},
"i":1
},
{
"_key":"12198",
"_id":"products/12198",
"_rev":"_WQ47fbi--_",
"a":{
"k":1,
"j":1
},
"i":1
},
{
"_key":"12205",
"_id":"products/12205",
"_rev":"_WQ47fbi--D",
"i":1
}
],
"hasMore":false,
"count":4,
"error":false,
"code":201
}
Example:Matchinganattributewhichisasub-document
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example<<EOF
{
"collection":"products",
"example":{
"a.j":1
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12228",
"_id":"products/12228",
"_rev":"_WQ47fcK--B",
"a":{
"j":1
},
"i":1
},
{
"_key":"12224",
"_id":"products/12224",
"_rev":"_WQ47fcK--_",
"a":{
"k":1,
"j":1
},
Hash
286
"i":1
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
Example:Matchinganattributewithinasub-document
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12254",
"_id":"products/12254",
"_rev":"_WQ47fcq--B",
"a":{
"j":1
},
"i":1
}
],
"hasMore":false,
"count":1,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Matchinganattribute
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example
<<EOF
{
"collection":"products",
"example":{
"i":1
}
}
EOF
Hash
287
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyMatchinganattributewhichisasub-document
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example
<<EOF
{
"collection":"products",
"example":{
"a.j":1
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyMatchinganattributewithinasub-document
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example
<<EOF
{
"collection":"products",
"example":{
"a":{
"j":1
}
}
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Finddocumentsmatchinganexample
returnsonedocumentofacollectionmatchingagivenexample
PUT/_api/simple/first-example
AJSONobjectwiththesepropertiesisrequired:
example:Theexampledocument.collection:Thenameofthecollectiontoquery.
Hash
288
Thiswillreturnthefirstdocumentmatchingagivenexample.
ReturnsaresultcontainingthedocumentorHTTP404ifnodocumentmatchedtheexample.
Ifmorethanonedocumentinthecollectionmatchesthespecifiedexample,onlyoneofthesedocumentswillbereturned,anditisundefinedwhichofthematchingdocumentsisreturned.
Example:Ifamatchingdocumentwasfound
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-example<<EOF
{
"collection":"products",
"example":{
"i":1
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"document":{
"_key":"12286",
"_id":"products/12286",
"_rev":"_WQ47fdO--F",
"a":{
"k":2,
"j":2
},
"i":1
},
"error":false,
"code":200
}
Example:Ifnodocumentwasfound
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-example<<EOF
{
"collection":"products",
"example":{
"l":1
}
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"code":404,
"errorNum":404,
"errorMessage":"nomatch"
}
ReturnCodes
200:isreturnedwhenthequerywassuccessfullyexecuted.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocument
Hash
289
inthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Ifamatchingdocumentwasfound
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-
example<<EOF
{
"collection":"products",
"example":{
"i":1
}
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyIfnodocumentwasfound
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-
example<<EOF
{
"collection":"products",
"example":{
"l":1
}
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Hash
290
WorkingwithSkiplistIndexesIfasuitableskip-listindexexists,then/_api/simple/rangeandotheroperationswillusethisindextoexecutequeries.
Createskiplist
createsaskip-list
POST/_api/index#skiplist
QueryParameters
collection-name(required):Thecollectionname.
AJSONobjectwiththesepropertiesisrequired:
fields(string):anarrayofattributepaths.unique:iftrue,thencreateauniqueindex.type:mustbeequalto"skiplist" .sparse:iftrue,thencreateasparseindex.deduplicate:iffalse,thededuplicationofarrayvaluesisturnedoff.
Createsaskip-listindexforthecollectioncollection-name,ifitdoesnotalreadyexist.Thecallexpectsanobjectcontainingtheindexdetails.
Inasparseindexalldocumentswillbeexcludedfromtheindexthatdonotcontainatleastoneofthespecifiedindexattributes(i.e.fields)orthathaveavalueofnullinanyofthespecifiedindexattributes.Suchdocumentswillnotbeindexed,andnotbetakenintoaccountforuniquenesschecksiftheuniqueflagisset.
Inanon-sparseindex,thesedocumentswillbeindexed(fornon-presentindexedattributes,avalueofnullwillbeused)andwillbetakenintoaccountforuniquenesschecksiftheuniqueflagisset.
Note:uniqueindexesonnon-shardkeysarenotsupportedinacluster.
Example:Creatingaskiplistindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"skiplist",
"unique":false,
"fields":[
"a",
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deduplicate":true,
"fields":[
"a",
"b"
],
"id":"products/11868",
"isNewlyCreated":true,
"sparse":false,
"type":"skiplist",
"unique":false,
"error":false,
Skiplist
291
"code":201
}
Example:Creatingasparseskiplistindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"skiplist",
"unique":false,
"sparse":true,
"fields":[
"a"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deduplicate":true,
"fields":[
"a"
],
"id":"products/11924",
"isNewlyCreated":true,
"sparse":true,
"type":"skiplist",
"unique":false,
"error":false,
"code":201
}
ReturnCodes
200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.400:Ifthecollectionalreadycontainsdocumentsandyoutrytocreateauniqueskip-listindexinsuchawaythattherearedocumentsviolatingtheuniqueness,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Creatingaskiplistindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"skiplist",
"unique":false,
"fields":[
"a",
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Skiplist
292
showresponsebodyCreatingasparseskiplistindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"skiplist",
"unique":false,
"sparse":true,
"fields":[
"a"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Skiplist
293
WorkingwithPersistentIndexesIfasuitablepersistentindexexists,then/_api/simple/rangeandotheroperationswillusethisindextoexecutequeries.
Createapersistentindex
createsapersistentindex
POST/_api/index#persistent
QueryParameters
collection-name(required):Thecollectionname.
AJSONobjectwiththesepropertiesisrequired:
fields(string):anarrayofattributepaths.unique:iftrue,thencreateauniqueindex.type:mustbeequalto"persistent" .sparse:iftrue,thencreateasparseindex.
Createsapersistentindexforthecollectioncollection-name,ifitdoesnotalreadyexist.Thecallexpectsanobjectcontainingtheindexdetails.
Inasparseindexalldocumentswillbeexcludedfromtheindexthatdonotcontainatleastoneofthespecifiedindexattributes(i.e.fields)orthathaveavalueofnullinanyofthespecifiedindexattributes.Suchdocumentswillnotbeindexed,andnotbetakenintoaccountforuniquenesschecksiftheuniqueflagisset.
Inanon-sparseindex,thesedocumentswillbeindexed(fornon-presentindexedattributes,avalueofnullwillbeused)andwillbetakenintoaccountforuniquenesschecksiftheuniqueflagisset.
Note:uniqueindexesonnon-shardkeysarenotsupportedinacluster.
Example:Creatingapersistentindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"persistent",
"unique":false,
"fields":[
"a",
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deduplicate":true,
"fields":[
"a",
"b"
],
"id":"products/11854",
"isNewlyCreated":true,
"sparse":false,
"type":"persistent",
"unique":false,
"error":false,
"code":201
Persistent
294
}
Example:Creatingasparsepersistentindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"persistent",
"unique":false,
"sparse":true,
"fields":[
"a"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"deduplicate":true,
"fields":[
"a"
],
"id":"products/11910",
"isNewlyCreated":true,
"sparse":true,
"type":"persistent",
"unique":false,
"error":false,
"code":201
}
ReturnCodes
200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.400:Ifthecollectionalreadycontainsdocumentsandyoutrytocreateauniquepersistentindexinsuchawaythattherearedocumentsviolatingtheuniqueness,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Creatingapersistentindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"persistent",
"unique":false,
"fields":[
"a",
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Persistent
295
showresponsebodyCreatingasparsepersistentindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"persistent",
"unique":false,
"sparse":true,
"fields":[
"a"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Persistent
296
WorkingwithGeoIndexes
Creategeo-spatialindex
createsageoindex
POST/_api/index#geo
QueryParameters
collection(required):Thecollectionname.
AJSONobjectwiththesepropertiesisrequired:
fields(string):Anarraywithoneortwoattributepaths.Ifitisanarraywithoneattributepathlocation,thenageo-spatialindexonalldocumentsiscreatedusinglocationaspathtothecoordinates.Thevalueoftheattributemustbeanarraywithatleasttwodoublevalues.Thearraymustcontainthelatitude(firstvalue)andthelongitude(secondvalue).Alldocuments,whichdonothavetheattributepathorwithvaluethatarenotsuitable,areignored.Ifitisanarraywithtwoattributepathslatitudeandlongitude,thenageo-spatialindexonalldocumentsiscreatedusinglatitudeandlongitudeaspathsthelatitudeandthelongitude.Thevalueoftheattributelatitudeandoftheattributelongitudemustadouble.Alldocuments,whichdonothavetheattributepathsorwhichvaluesarenotsuitable,areignored.type:mustbeequalto"geo" .geoJson:Ifageo-spatialindexonalocationisconstructedandgeoJsonistrue,thentheorderwithinthearrayislongitudefollowedbylatitude.Thiscorrespondstotheformatdescribedinhttp://geojson.org/geojson-spec.html#positions
NOTESwaggerexampleswon'tworkduetotheanchor.
Createsageo-spatialindexinthecollectioncollection-name,ifitdoesnotalreadyexist.Expectsanobjectcontainingtheindexdetails.
Geoindexesarealwayssparse,meaningthatdocumentsthatdonotcontaintheindexattributesorhavenon-numericvaluesintheindexattributeswillnotbeindexed.
Example:Creatingageoindexwithalocationattribute
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"geo",
"fields":[
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"constraint":false,
"fields":[
"b"
],
"geoJson":false,
"id":"products/11812",
"ignoreNull":true,
"isNewlyCreated":true,
"sparse":true,
"type":"geo1",
"unique":false,
"error":false,
"code":201
}
Geo
297
Example:Creatingageoindexwithlatitudeandlongitudeattributes
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"geo",
"fields":[
"e",
"f"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"constraint":false,
"fields":[
"e",
"f"
],
"id":"products/11798",
"ignoreNull":true,
"isNewlyCreated":true,
"sparse":true,
"type":"geo2",
"unique":false,
"error":false,
"code":201
}
ReturnCodes
200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Creatingageoindexwithalocationattribute
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"geo",
"fields":[
"b"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyCreatingageoindexwithlatitudeandlongitudeattributes
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
Geo
298
{
"type":"geo",
"fields":[
"e",
"f"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Returnsdocumentsnearacoordinate
returnsalldocumentsofacollectionnearagivenlocation
PUT/_api/simple/near
AJSONobjectwiththesepropertiesisrequired:
distance:Ifgiven,theattributekeyusedtoreturnthedistancetothegivencoordinate.(optional).Ifspecified,distancesarereturnedinmeters.skip:Thenumberofdocumentstoskipinthequery.(optional)longitude:Thelongitudeofthecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)collection:Thenameofthecollectiontoquery.latitude:Thelatitudeofthecoordinate.geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)
Thedefaultwillfindatmost100documentsnearthegivencoordinate.Thereturnedarrayissortedaccordingtothedistance,withthenearestdocumentbeingfirstinthereturnarray.Ifthereareneardocumentsofequaldistance,documentsarechosenrandomlyfromthissetuntilthelimitisreached.
Inordertousethenearoperator,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Note:thenearsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheNEARfunctionasfollows:
FORdocINNEAR(@@collection,@latitude,@longitude,@limit)
RETURNdoc`
Example:Withoutdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":2
}
Geo
299
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12441",
"_id":"products/12441",
"_rev":"_WQ47fgq--D",
"name":"Name/0.002/",
"loc":[
0.002,
0
]
},
{
"_key":"12435",
"_id":"products/12435",
"_rev":"_WQ47fgq--_",
"name":"Name/-0.002/",
"loc":[
-0.002,
0
]
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
Example:Withdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":3,
"distance":"distance"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"distance":222.38985328911744,
"_id":"products/12486",
"_key":"12486",
"_rev":"_WQ47fhq--D",
"loc":[
-0.002,
0
],
"name":"Name/-0.002/"
},
{
"distance":222.38985328911744,
"_id":"products/12492",
"_key":"12492",
"_rev":"_WQ47fhq--H",
Geo
300
"loc":[
0.002,
0
],
"name":"Name/0.002/"
},
{
"distance":444.779706578235,
"_id":"products/12483",
"_key":"12483",
"_rev":"_WQ47fhq--B",
"loc":[
-0.004,
0
],
"name":"Name/-0.004/"
}
],
"hasMore":false,
"count":3,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Withoutdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":2
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyWithdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":3,
"distance":"distance"
}
EOF
Geo
301
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Finddocumentswithinaradiusaroundacoordinate
returnsalldocumentsofacollectionwithinagivenradius
PUT/_api/simple/within
AJSONobjectwiththesepropertiesisrequired:
distance:Ifgiven,theattributekeyusedtoreturnthedistancetothegivencoordinate.(optional).Ifspecified,distancesarereturnedinmeters.skip:Thenumberofdocumentstoskipinthequery.(optional)longitude:Thelongitudeofthecoordinate.radius:Themaximalradius(inmeters).collection:Thenameofthecollectiontoquery.latitude:Thelatitudeofthecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)
Thiswillfindalldocumentswithinagivenradiusaroundthecoordinate(latitude,longitude).Thereturnedlistissortedbydistance.
Inordertousethewithinoperator,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Note:thewithinsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheWITHINfunctionasfollows:
FORdocINWITHIN(@@collection,@latitude,@longitude,@radius,@distanceAttributeName)
RETURNdoc
Example:Withoutdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":2,
"radius":500
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"_key":"12854",
"_id":"products/12854",
Geo
302
"_rev":"_WQ47foi--_",
"name":"Name/0.002/",
"loc":[
0.002,
0
]
},
{
"_key":"12848",
"_id":"products/12848",
"_rev":"_WQ47foe--H",
"name":"Name/-0.002/",
"loc":[
-0.002,
0
]
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
Example:Withdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":3,
"distance":"distance",
"radius":300
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"result":[
{
"distance":222.38985328911744,
"_id":"products/12899",
"_key":"12899",
"_rev":"_WQ47fpW--B",
"loc":[
-0.002,
0
],
"name":"Name/-0.002/"
},
{
"distance":222.38985328911744,
"_id":"products/12905",
"_key":"12905",
"_rev":"_WQ47fpW--F",
"loc":[
0.002,
0
],
"name":"Name/0.002/"
},
{
"distance":444.779706578235,
"_id":"products/12896",
"_key":"12896",
Geo
303
"_rev":"_WQ47fpW--_",
"loc":[
-0.004,
0
],
"name":"Name/-0.004/"
}
],
"hasMore":false,
"count":3,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
Withoutdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":2,
"radius":500
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyWithdistance
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF
{
"collection":"products",
"latitude":0,
"longitude":0,
"skip":1,
"limit":3,
"distance":"distance",
"radius":300
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Geo
304
showresponsebody
Geo
305
FulltextIfafulltextindexexists,then/_api/simple/fulltextwillusethisindextoexecutethespecifiedfulltextquery.
Createfulltextindex
createsafulltextindex
POST/_api/index#fulltext
QueryParameters
collection-name(required):Thecollectionname.
AJSONobjectwiththesepropertiesisrequired:
fields(string):anarrayofattributenames.Currently,thearrayislimitedtoexactlyoneattribute.type:mustbeequalto"fulltext" .minLength:Minimumcharacterlengthofwordstoindex.Willdefaulttoaserver-definedvalueifunspecified.Itisthusrecommendedtosetthisvalueexplicitlywhencreatingtheindex.
NOTESwaggerexampleswon'tworkduetotheanchor.
Createsafulltextindexforthecollectioncollection-name,ifitdoesnotalreadyexist.Thecallexpectsanobjectcontainingtheindexdetails.
Example:Creatingafulltextindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF
{
"type":"fulltext",
"fields":[
"text"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"fields":[
"text"
],
"id":"products/11826",
"isNewlyCreated":true,
"minLength":2,
"sparse":true,
"type":"fulltext",
"unique":false,
"error":false,
"code":201
}
ReturnCodes
200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.
Examples
Fulltext
306
Creatingafulltextindex
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?
collection=products<<EOF
{
"type":"fulltext",
"fields":[
"text"
]
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Fulltextindexquery
returnsdocumentsofacollectionasaresultofafulltextquery
PUT/_api/simple/fulltext
AJSONobjectwiththesepropertiesisrequired:
index:Theidentifierofthefulltext-indextouse.attribute:Theattributethatcontainsthetexts.collection:Thenameofthecollectiontoquery.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)skip:Thenumberofdocumentstoskipinthequery(optional).query:Thefulltextquery.PleaserefertoFulltextqueriesfordetails.
Thiswillfindalldocumentsfromthecollectionthatmatchthefulltextqueryspecifiedinquery.
Inordertousethefulltextoperator,afulltextindexmustbedefinedforthecollectionandthespecifiedattribute.
Returnsacursorcontainingtheresult,seeHttpCursorfordetails.
Note:thefulltextsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheFULLTEXTAQLfunctionasfollows:
FORdocINFULLTEXT(@@collection,@attributeName,@queryString,@limit)
RETURNdoc
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/fulltext<<EOF
{
"collection":"products",
"attribute":"text",
"query":"word"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Fulltext
307
{
"result":[
{
"_key":"12326",
"_id":"products/12326",
"_rev":"_WQ47feO--_",
"text":"thistextcontainsword"
},
{
"_key":"12330",
"_id":"products/12330",
"_rev":"_WQ47feS--_",
"text":"thistextalsohasaword"
}
],
"hasMore":false,
"count":2,
"error":false,
"code":201
}
ReturnCodes
201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.
Examples
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/fulltext
<<EOF
{
"collection":"products",
"attribute":"text",
"query":"word"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Fulltext
308
HTTPInterfaceforTransactions
Transactions
ArangoDB'stransactionsareexecutedontheserver.Transactionscanbeinitiatedbyclientsbysendingthetransactiondescriptionforexecutiontotheserver.
TransactionsinArangoDBdonotofferseparateBEGIN,COMMITandROLLBACKoperationsastheyareavailableinmanyotherdatabaseproducts.Instead,ArangoDBtransactionsaredescribedbyaJavaScriptfunction,andthecodeinsidetheJavaScriptfunctionwillthenbeexecutedtransactionally.Attheendofthefunction,thetransactionisautomaticallycommitted,andallchangesdonebythetransactionwillbepersisted.Ifanexceptionisthrownduringtransactionexecution,alloperationsperformedinthetransactionarerolledback.
ForamoredetaileddescriptionofhowtransactionsworkinArangoDBpleaserefertoTransactions.
Executetransaction
executeaserver-sidetransaction
POST/_api/transaction
AJSONobjectwiththesepropertiesisrequired:
maxTransactionSize:Transactionsizelimitinbytes.HonoredbytheRocksDBstorageengineonly.lockTimeout:anoptionalnumericvaluethatcanbeusedtosetatimeoutforwaitingoncollectionlocks.Ifnotspecified,adefaultvaluewillbeused.SettinglockTimeoutto0willmakeArangoDBnottimeoutwaitingforalock.waitForSync:anoptionalbooleanflagthat,ifset,willforcethetransactiontowritealldatatodiskbeforereturning.intermediateCommitCount:Maximumnumberofoperationsafterwhichanintermediatecommitisperformedautomatically.HonoredbytheRocksDBstorageengineonly.params:optionalargumentspassedtoaction.intermediateCommitSize:Maximumtotalsizeofoperationsafterwhichanintermediatecommitisperformedautomatically.HonoredbytheRocksDBstorageengineonly.action:theactualtransactionoperationstobeexecuted,intheformofstringifiedJavaScriptcode.Thecodewillbeexecutedonserverside,withlatebinding.Itisthuscriticalthatthecodespecifiedinactionproperlysetsupallthevariablesitneeds.Ifthecodespecifiedinactionendswithareturnstatement,thevaluereturnedwillalsobereturnedbytheRESTAPIintheresultattributeifthetransactioncommittedsuccessfully.collections:collectionsmustbeaJSONobjectthatcanhaveeitherorbothsub-attributesreadandwrite,eachbeinganarrayofcollectionnamesorasinglecollectionnameasstring.Collectionsthatwillbewrittentointhetransactionmustbedeclaredwiththewriteattributeoritwillfail,whereasnon-declaredcollectionsfromwhichissolelyreadwillbeaddedlazily.Theoptionalsub-attributeallowImplicitcanbesettofalsetolettransactionsfailincaseofundeclaredcollectionsforreading.Collectionsforreadingshouldbefullydeclaredifpossible,toavoiddeadlocks.
ThetransactiondescriptionmustbepassedinthebodyofthePOSTrequest.
Ifthetransactionisfullyexecutedandcommittedontheserver,HTTP200willbereturned.Additionally,thereturnvalueofthecodedefinedinactionwillbereturnedintheresultattribute.
Forsuccessfullycommittedtransactions,thereturnedJSONobjecthasthefollowingproperties:
error:booleanflagtoindicateifanerroroccurred(falseinthiscase)
code:theHTTPstatuscode
result:thereturnvalueofthetransaction
Ifthetransactionspecificationiseithermissingormalformed,theserverwillrespondwithHTTP400.
ThebodyoftheresponsewillthencontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:
error:booleanflagtoindicatethatanerroroccurred(trueinthiscase)
code:theHTTPstatuscode
Transactions
309
errorNum:theservererrornumber
errorMessage:adescriptiveerrormessage
Ifatransactionfailstocommit,eitherbyanexceptionthrownintheactioncode,orbyaninternalerror,theserverwillrespondwithanerror.AnyothererrorswillbereturnedwithanyofthereturncodesHTTP400,HTTP409,orHTTP500.
Example:Executingatransactiononasinglecollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"write":"products"
},
"action":"function(){vardb=require('@arangodb').db;db.products.save({});returndb.products.count();}"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":1
}
Example:Executingatransactionusingmultiplecollections
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"write":[
"products",
"materials"
]
},
"action":"function(){vardb=require('@arangodb').db;db.products.save({});db.materials.save({});return'worked!';}"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":"worked!"
}
Example:Abortingatransactionduetoaninternalerror
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"write":"products"
Transactions
310
},
"action":"function(){vardb=require('@arangodb').db;db.products.save({_key:'abc'});db.products.save({_key:'abc'});}
"
}
EOF
HTTP/1.1409Conflict
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"uniqueconstraintviolated-inindex0oftypeprimaryover[\"_key\"];conflictingkey:abc",
"code":409,
"errorNum":1210
}
Example:Abortingatransactionbyexplicitlythrowinganexception
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"read":"products"
},
"action":"function(){throw'doh!';}"
}
EOF
HTTP/1.1500InternalServerError
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"transactionnotrunningoncommit",
"code":500,
"errorNum":1650
}
Example:Referringtoanon-existingcollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"read":"products"
},
"action":"function(){returntrue;}"
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"errorMessage":"collectionnotfound:products",
"code":404,
"errorNum":1203
}
ReturnCodes
Transactions
311
200:Ifthetransactionisfullyexecutedandcommittedontheserver,HTTP200willbereturned.400:Ifthetransactionspecificationiseithermissingormalformed,theserverwillrespondwithHTTP400.404:Ifthetransactionspecificationcontainsanunknowncollection,theserverwillrespondwithHTTP404.500:ExceptionsthrownbyuserswillmaketheserverrespondwithareturncodeofHTTP500
Examples
Executingatransactiononasinglecollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"write":"products"
},
"action":"function(){vardb=require('@arangodb').db;db.products.save({});
returndb.products.count();}"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyExecutingatransactionusingmultiplecollections
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"write":[
"products",
"materials"
]
},
"action":"function(){vardb=
require('@arangodb').db;db.products.save({});db.materials.save({});return'worked!';}"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyAbortingatransactionduetoaninternalerror
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"write":"products"
},
"action":"function(){vardb=require('@arangodb').db;db.products.save({_key:
'abc'});db.products.save({_key:'abc'});}"
}
Transactions
312
EOF
HTTP/1.1409Conflict
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyAbortingatransactionbyexplicitlythrowinganexception
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"read":"products"
},
"action":"function(){throw'doh!';}"
}
EOF
HTTP/1.1500InternalServerError
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyReferringtoanon-existingcollection
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF
{
"collections":{
"read":"products"
},
"action":"function(){returntrue;}"
}
EOF
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Transactions
313
HTTPInterfaceforReplication
Replication
ThisisanintroductiontoArangoDB'sHTTPreplicationinterface.ThereplicationarchitectureandcomponentsaredescribedinmoredetailsinReplication.
TheHTTPreplicationinterfaceservesfourmainpurposes:
fetchinitialdatafromaserver(e.g.forabackup,orfortheinitialsynchronizationofdatabeforestartingthecontinuousreplicationapplier)queryingthestateofamasterfetchcontinuouschangesfromamaster(usedforincrementalsynchronizationofchanges)administerthereplicationapplier(starting,stopping,configuring,queryingstate)onaslave
Pleasenotethatallreplicationoperationsworkonaper-databaselevel.IfanArangoDBservercontainsmorethanonedatabase,thereplicationsystemmustbeconfiguredindividuallyperdatabase,andreplicatingthedataofmultipledatabaseswillrequiremultipleoperations.
Replication
314
ReplicationDumpCommandsTheinventorymethodcanbeusedtoqueryanArangoDBdatabase'scurrentsetofcollectionsplustheirindexes.Clientscanusethismethodtogetanoverviewofwhichcollectionsarepresentinthedatabase.Theycanusethisinformationtoeitherstartafullorapartialsynchronizationofdata,e.g.toinitiateabackuportheincrementaldatasynchronization.
Returninventoryofcollectionsandindexes
Returnsanoverviewofcollectionsandtheirindexes
GET/_api/replication/inventory
QueryParameters
includeSystem(optional):Includesystemcollectionsintheresult.Thedefaultvalueistrue.
Returnsthearrayofcollectionsandindexesavailableontheserver.Thisarraycanbeusedbyreplicationclientstoinitiateaninitialsyncwiththeserver.
TheresponsewillcontainaJSONobjectwiththecollectionandstateandtickattributes.
collectionsisanarrayofcollectionswiththefollowingsub-attributes:
parameters:thecollectionproperties
indexes:anarrayoftheindexesofathecollection.Primaryindexesandedgeindexesarenotincludedinthisarray.
Thestateattributecontainsthecurrentstateofthereplicationlogger.Itcontainsthefollowingsub-attributes:
running:whetherornotthereplicationloggeriscurrentlyactive.Note:sinceArangoDB2.2,thevaluewillalwaysbetrue
lastLogTick:thevalueofthelasttickthereplicationloggerhaswritten
time:thecurrenttimeontheserver
ReplicationclientsshouldnotethelastLogTickvaluereturned.Theycanthenfetchcollections'datausingthedumpmethoduptothevalueoflastLogTick,andquerythecontinuousreplicationlogforlogeventsafterthistickvalue.
Tocreateafullcopyofthecollectionsontheserver,areplicationclientcanexecutethesesteps:
callthe/inventoryAPImethod.ThisreturnsthelastLogTickvalueandthearrayofcollectionsandindexesfromtheserver.
foreachcollectionreturnedby/inventory,createthecollectionlocallyandcall/dumptostreamthecollectiondatatotheclient,uptothevalueoflastLogTick.Afterthat,theclientcancreatetheindexesonthecollectionsastheywerereportedby/inventory.
Iftheclientswantstocontinuouslystreamreplicationlogeventsfromtheloggerserver,thefollowingadditionalstepsneedtobecarriedout:
theclientshouldcall/logger-followinitiallytofetchthefirstbatchofreplicationeventsthatwereloggedaftertheclient'scallto/inventory.
Thecallto/logger-followshoulduseafromparameterwiththevalueofthelastLogTickasreportedby/inventory.Thecallto/logger-followwillreturnthex-arango-replication-lastincludedwhichwillcontainthelasttickvalueincludedintheresponse.
theclientcanthencontinuouslycall/logger-followtoincrementallyfetchnewreplicationeventsthatoccurredafterthelasttransfer.
Callsshoulduseafromparameterwiththevalueofthex-arango-replication-lastincludedheaderofthepreviousresponse.Iftherearenomorereplicationevents,theresponsewillbeemptyandclientscangotosleepforawhileandtryagainlater.
Note:onacoordinator,thisrequestmusthavethequeryparameterDBserverwhichmustbeanIDofaDBserver.TheverysamerequestisforwardedsynchronouslytothatDBserver.Itisanerrorifthisattributeisnotboundinthecoordinatorcase.
Example:
ReplicationDump
315
shell>curl--dump-http://localhost:8529/_api/replication/inventory
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"collections":[
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"60",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_appbundles",
"id":"60",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":2097152,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"_appbundles",
"numberOfShards":1,
"planId":"60",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"26",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_aqlfunctions",
"id":"26",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
ReplicationDump
316
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":1048576,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"_aqlfunctions",
"numberOfShards":1,
"planId":"26",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"43",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_frontend",
"id":"43",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":1048576,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"_frontend",
"numberOfShards":1,
"planId":"43",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
ReplicationDump
317
"parameters":{
"allowUserKeys":true,
"cid":"2",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_graphs",
"id":"2",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":1048576,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"_graphs",
"numberOfShards":1,
"planId":"2",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"11",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_modules",
"id":"11",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":1048576,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":9899
ReplicationDump
318
},
"name":"_modules",
"numberOfShards":1,
"planId":"11",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"13",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_routing",
"id":"13",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":4194304,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":9948
},
"name":"_routing",
"numberOfShards":1,
"planId":"13",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[
{
"id":"9",
"type":"hash",
"fields":[
"user"
],
"selectivityEstimate":1,
"unique":true,
"sparse":true,
"deduplicate":true
}
ReplicationDump
319
],
"parameters":{
"allowUserKeys":true,
"cid":"6",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_users",
"id":"6",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
},
{
"id":"9",
"type":"hash",
"fields":[
"user"
],
"selectivityEstimate":1,
"unique":true,
"sparse":true,
"deduplicate":true
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":4194304,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":11963
},
"name":"_users",
"numberOfShards":1,
"planId":"6",
"replicationFactor":2,
"shardKeys":[
"user"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"98",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"h68719E5AC6E7/98",
"id":"98",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
ReplicationDump
320
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":false,
"isVolatile":false,
"journalSize":33554432,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"animals",
"numberOfShards":1,
"planId":"98",
"replicationFactor":1,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"92",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"h68719E5AC6E7/92",
"id":"92",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":false,
"isVolatile":false,
"journalSize":33554432,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"demo",
"numberOfShards":1,
"planId":"92",
"replicationFactor":1,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
}
],
ReplicationDump
321
"state":{
"running":true,
"lastLogTick":"12006",
"lastUncommittedLogTick":"12016",
"totalEvents":4132,
"time":"2018-01-25T19:13:45Z"
},
"tick":"12016"
}
Example:Withsomeadditionalindexes:
shell>curl--dump-http://localhost:8529/_api/replication/inventory
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"collections":[
{
"indexes":[
{
"id":"12021",
"type":"hash",
"fields":[
"name"
],
"selectivityEstimate":1,
"unique":false,
"sparse":false,
"deduplicate":true
},
{
"id":"12024",
"type":"skiplist",
"fields":[
"a",
"b"
],
"unique":true,
"sparse":false,
"deduplicate":true
}
],
"parameters":{
"allowUserKeys":true,
"cid":"12017",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"h68719E5AC6E7/12017",
"id":"12017",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
},
{
"id":"12021",
"type":"hash",
"fields":[
"name"
ReplicationDump
322
],
"selectivityEstimate":1,
"unique":false,
"sparse":false,
"deduplicate":true
},
{
"id":"12024",
"type":"skiplist",
"fields":[
"a",
"b"
],
"unique":true,
"sparse":false,
"deduplicate":true
}
],
"isSmart":false,
"isSystem":false,
"isVolatile":false,
"journalSize":33554432,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"IndexedCollection1",
"numberOfShards":1,
"planId":"12017",
"replicationFactor":1,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[
{
"id":"12030",
"type":"fulltext",
"fields":[
"text"
],
"unique":false,
"sparse":true,
"minLength":10
},
{
"id":"12033",
"type":"skiplist",
"fields":[
"a"
],
"unique":false,
"sparse":false,
"deduplicate":true
}
],
"parameters":{
"allowUserKeys":true,
"cid":"12026",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"h68719E5AC6E7/12026",
"id":"12026",
"indexBuckets":8,
"indexes":[
{
ReplicationDump
323
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
},
{
"id":"12030",
"type":"fulltext",
"fields":[
"text"
],
"unique":false,
"sparse":true,
"minLength":10
},
{
"id":"12033",
"type":"skiplist",
"fields":[
"a"
],
"unique":false,
"sparse":false,
"deduplicate":true
}
],
"isSmart":false,
"isSystem":false,
"isVolatile":false,
"journalSize":33554432,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"IndexedCollection2",
"numberOfShards":1,
"planId":"12026",
"replicationFactor":1,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"60",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_appbundles",
"id":"60",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
ReplicationDump
324
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":2097152,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"_appbundles",
"numberOfShards":1,
"planId":"60",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"26",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_aqlfunctions",
"id":"26",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":1048576,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"_aqlfunctions",
"numberOfShards":1,
"planId":"26",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
ReplicationDump
325
"cid":"43",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_frontend",
"id":"43",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":1048576,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"_frontend",
"numberOfShards":1,
"planId":"43",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"2",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_graphs",
"id":"2",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":1048576,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"_graphs",
ReplicationDump
326
"numberOfShards":1,
"planId":"2",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"11",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_modules",
"id":"11",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":1048576,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":9899
},
"name":"_modules",
"numberOfShards":1,
"planId":"11",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"13",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_routing",
"id":"13",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
ReplicationDump
327
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":4194304,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":9948
},
"name":"_routing",
"numberOfShards":1,
"planId":"13",
"replicationFactor":2,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[
{
"id":"9",
"type":"hash",
"fields":[
"user"
],
"selectivityEstimate":1,
"unique":true,
"sparse":true,
"deduplicate":true
}
],
"parameters":{
"allowUserKeys":true,
"cid":"6",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"_users",
"id":"6",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
},
{
"id":"9",
"type":"hash",
"fields":[
"user"
],
"selectivityEstimate":1,
"unique":true,
"sparse":true,
"deduplicate":true
ReplicationDump
328
}
],
"isSmart":false,
"isSystem":true,
"isVolatile":false,
"journalSize":4194304,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":11963
},
"name":"_users",
"numberOfShards":1,
"planId":"6",
"replicationFactor":2,
"shardKeys":[
"user"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
"allowUserKeys":true,
"cid":"98",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"h68719E5AC6E7/98",
"id":"98",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":false,
"isVolatile":false,
"journalSize":33554432,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"animals",
"numberOfShards":1,
"planId":"98",
"replicationFactor":1,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
},
{
"indexes":[],
"parameters":{
ReplicationDump
329
"allowUserKeys":true,
"cid":"92",
"count":0,
"deleted":false,
"doCompact":true,
"globallyUniqueId":"h68719E5AC6E7/92",
"id":"92",
"indexBuckets":8,
"indexes":[
{
"id":"0",
"type":"primary",
"fields":[
"_key"
],
"selectivityEstimate":1,
"unique":true,
"sparse":false
}
],
"isSmart":false,
"isSystem":false,
"isVolatile":false,
"journalSize":33554432,
"keyOptions":{
"type":"traditional",
"allowUserKeys":true,
"lastValue":0
},
"name":"demo",
"numberOfShards":1,
"planId":"92",
"replicationFactor":1,
"shardKeys":[
"_key"
],
"shards":{
},
"status":3,
"type":2,
"version":6,
"waitForSync":false
}
}
],
"state":{
"running":true,
"lastLogTick":"12006",
"lastUncommittedLogTick":"12034",
"totalEvents":4138,
"time":"2018-01-25T19:13:45Z"
},
"tick":"12034"
}
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
Examples
shell>curl--dump-http://localhost:8529/_api/replication/inventory
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
ReplicationDump
330
Withsomeadditionalindexes:
shell>curl--dump-http://localhost:8529/_api/replication/inventory
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyThebatchmethodwillcreateasnapshotofthecurrentstatethatthencanbedumped.AbatchIdisrequiredwhenusingthedumpapiwithrocksdb.
Createnewdumpbatch
handleadumpbatchcommand
POST/_api/replication/batchNote:Thesecallsareuninterestingtousers.
AJSONobjectwiththesepropertiesisrequired:
ttl:thetime-to-liveforthenewbatch(inseconds)AJSONobjectwiththebatchconfiguration.
Createsanewdumpbatchandreturnsthebatch'sid.
TheresponseisaJSONobjectwiththefollowingattributes:
id:theidofthebatch
Note:onacoordinator,thisrequestmusthavethequeryparameterDBserverwhichmustbeanIDofaDBserver.TheverysamerequestisforwardedsynchronouslytothatDBserver.Itisanerrorifthisattributeisnotboundinthecoordinatorcase.
ReturnCodes
200:isreturnedifthebatchwascreatedsuccessfully.400:isreturnedifthettlvalueisinvalidorifDBserverattributeisnotspecifiedorillegalonacoordinator.405:isreturnedwhenaninvalidHTTPmethodisused.
Deletesanexistingdumpbatch
handleadumpbatchcommand
DELETE/_api/replication/batch/{id}Note:Thesecallsareuninterestingtousers.
PathParameters
id(required):Theidofthebatch.
Deletestheexistingdumpbatch,allowingcompactionandcleanuptoresume.
Note:onacoordinator,thisrequestmusthavethequeryparameterDBserverwhichmustbeanIDofaDBserver.TheverysamerequestisforwardedsynchronouslytothatDBserver.Itisanerrorifthisattributeisnotboundinthecoordinatorcase.
ReturnCodes
204:isreturnedifthebatchwasdeletedsuccessfully.400:isreturnedifthebatchwasnotfound.405:isreturnedwhenaninvalidHTTPmethodisused.
Prolongexistingdumpbatch
handleadumpbatchcommand
PUT/_api/replication/batch/{id}Note:Thesecallsareuninterestingtousers.
ReplicationDump
331
AJSONobjectwiththesepropertiesisrequired:
ttl:thetime-to-liveforthenewbatch(inseconds)
Extendsthettlofanexistingdumpbatch,usingthebatch'sidandtheprovidedttlvalue.
Ifthebatch'sttlcanbeextendedsuccessfully,theresponseisempty.
Note:onacoordinator,thisrequestmusthavethequeryparameterDBserverwhichmustbeanIDofaDBserver.TheverysamerequestisforwardedsynchronouslytothatDBserver.Itisanerrorifthisattributeisnotboundinthecoordinatorcase.
PathParameters
id(required):Theidofthebatch.
ReturnCodes
204:isreturnedifthebatch'sttlwasextendedsuccessfully.400:isreturnedifthettlvalueisinvalidorthebatchwasnotfound.405:isreturnedwhenaninvalidHTTPmethodisused.Thedumpmethodcanbeusedtofetchdatafromaspecificcollection.Astheresultsofthedumpcommandcanbehuge,dumpmaynotreturnalldatafromacollectionatonce.Instead,thedumpcommandmaybecalledrepeatedlybyreplicationclientsuntilthereisnomoredatatofetch.Thedumpcommandwillnotonlyreturnthecurrentdocumentsinthecollection,butalsodocumentupdatesanddeletions.
Pleasenotethatthedumpmethodwillonlyreturndocuments,updatesanddeletionsfromacollection'sjournalsanddatafiles.Operationsthatarestoredinthewrite-aheadlogonlywillnotbereturned.Inordertoensurethattheseoperationsareincludedinadump,thewrite-aheadlogmustbeflushedfirst.
Togettoanidenticalstateofdata,replicationclientsshouldapplytheindividualpartsofthedumpresultsinthesameorderastheyareprovided.
Returndataofacollection
returnsthewholecontentofonecollection
GET/_api/replication/dump
QueryParameters
collection(required):Thenameoridofthecollectiontodump.chunkSize(optional):Approximatemaximumsizeofthereturnedresult.batchId(required):rocksdbonly-Theidofthesnapshottousefrom(optional):mmfilesonly-Lowerboundtickvalueforresults.to(optional):mmfilesonly-Upperboundtickvalueforresults.includeSystem(optional):mmfilesonly-Includesystemcollectionsintheresult.Thedefaultvalueistrue.ticks(optional):mmfilesonly-Whetherornottoincludetickvaluesinthedump.Thedefaultvalueistrue.flush(optional):mmfilesonly-WhetherornottoflushtheWALbeforedumping.Thedefaultvalueistrue.
Returnsthedatafromthecollectionfortherequestedrange.
Whenthefromqueryparameterisnotused,collectioneventsarereturnedfromthebeginning.Whenthefromparameterisused,theresultwillonlycontaincollectionentrieswhichhavehighertickvaluesthanthespecifiedfromvalue(note:thelogentrywithatickvalueequaltofromwillbeexcluded).
Thetoqueryparametercanbeusedtooptionallyrestricttheupperboundoftheresulttoacertaintickvalue.Ifused,theresultwillonlycontaincollectionentrieswithtickvaluesupto(including)to.
ThechunkSizequeryparametercanbeusedtocontrolthesizeoftheresult.Itmustbespecifiedinbytes.ThechunkSizevaluewillonlybehonoredapproximately.OtherwiseatoolowchunkSizevaluecouldcausetheservertonotbeabletoputjustoneentryintotheresultandreturnit.Therefore,thechunkSizevaluewillonlybeconsultedafteranentryhasbeenwrittenintotheresult.IftheresultsizeisthenbiggerthanchunkSize,theserverwillrespondwithasmanyentriesasthereareintheresponsealready.IftheresultsizeisstillsmallerthanchunkSize,theserverwilltrytoreturnmoredataifthere'smoredatalefttoreturn.
IfchunkSizeisnotspecified,someserver-sidedefaultvaluewillbeused.
ReplicationDump
332
TheContent-Typeoftheresultisapplication/x-arango-dump.Thisisaneasy-to-processformat,withallentriesgoingontoseparatelinesintheresponsebody.
EachlineitselfisaJSONobject,withatleastthefollowingattributes:
tick:theoperation'stickattribute
key:thekeyofthedocument/edgeorthekeyusedinthedeletionoperation
rev:therevisionidofthedocument/edgeorthedeletionoperation
data:theactualdocument/edgedatafortypes2300and2301.Thefulldocument/edgedatawillbereturnedevenforupdates.
type:thetypeofentry.Possiblevaluesfortypeare:
2300:documentinsertion/update
2301:edgeinsertion/update
2302:document/edgedeletion
Note:therewillbenodistinctionbetweeninsertsandupdateswhencallingthismethod.
Example:Emptycollection:
shell>curl--dump-http://localhost:8529/_api/replication/dump?collection=testCollection
HTTP/1.1204NoContent
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:false
x-arango-replication-lastincluded:0
Example:Non-emptycollection:
shell>curl--dump-http://localhost:8529/_api/replication/dump?collection=testCollection
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:false
x-arango-replication-lastincluded:11986
"{\"tick\":\"11980\",\"type\":2300,\"data\":{\"_id\":\"testCollection/123456\",\"_key\":\"123456\",\"_rev\":\"_WQ47bCW--D\",\"b
\":1,\"c\":false,\"d\":\"additionalvalue\"}}
{\"tick\":\"11984\",\"type\":2302,\"data\":{\"_key\":\"foobar\",\"_rev\":\"_WQ47bCa--B\"}}
{\"tick\":\"11986\",\"type\":2302,\"data\":{\"_key\":\"abcdef\",\"_rev\":\"_WQ47bCa--D\"}}
"
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfullyanddatawasreturned.Theheaderx-arango-replication-lastincludedissettothetickofthelastdocumentreturned.204:isreturnediftherequestwasexecutedsuccessfully,buttherewasnocontentavailable.Theheaderx-arango-replication-lastincludedis0inthiscase.400:isreturnedifeitherthefromortovaluesareinvalid.404:isreturnedwhenthecollectioncouldnotbefound.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
ReplicationDump
333
Examples
Emptycollection:
shell>curl--dump-http://localhost:8529/_api/replication/dump?collection=testCollection
HTTP/1.1204NoContent
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:false
x-arango-replication-lastincluded:0
Non-emptycollection:
shell>curl--dump-http://localhost:8529/_api/replication/dump?collection=testCollection
HTTP/1.1200OK
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:false
x-arango-replication-lastincluded:11986
"{\"tick\":\"11980\",\"type\":2300,\"data\":
{\"_id\":\"testCollection/123456\",\"_key\":\"123456\",\"_rev\":\"_WQ47bCW--
D\",\"b\":1,\"c\":false,\"d\":\"additional
value\"}}\n{\"tick\":\"11984\",\"type\":2302,\"data\":
{\"_key\":\"foobar\",\"_rev\":\"_WQ47bCa--
B\"}}\n{\"tick\":\"11986\",\"type\":2302,\"data\":
{\"_key\":\"abcdef\",\"_rev\":\"_WQ47bCa--D\"}}\n"
Synchronizedatafromaremoteendpoint
startareplication
PUT/_api/replication/sync
AJSONobjectwiththesepropertiesisrequired:
username:anoptionalArangoDBusernametousewhenconnectingtotheendpoint.includeSystem:whetherornotsystemcollectionoperationswillbeappliedendpoint:themasterendpointtoconnectto(e.g."tcp://192.168.173.13:8529").initialSyncMaxWaitTime:themaximumwaittime(inseconds)thattheinitialsynchronizationwillwaitforaresponsefromthemasterwhenfetchinginitialcollectiondata.Thiswaittimecanbeusedtocontrolafterwhattimetheinitialsynchronizationwillgiveupwaitingforaresponseandfail.Thisvaluewillbeignoredifsetto0.database:thedatabasenameonthemaster(ifnotspecified,defaultstothenameofthelocalcurrentdatabase).restrictType:anoptionalstringvalueforcollectionfiltering.Whenspecified,theallowedvaluesareincludeorexclude.incremental:ifsettotrue,thenanincrementalsynchronizationmethodwillbeusedforsynchronizingdataincollections.Thismethodisusefulwhencollectionsalreadyexistlocally,andonlytheremainingdifferencesneedtobetransferredfromtheremoteendpoint.Inthiscase,theincrementalsynchronizationcanbefasterthanafullsynchronization.Thedefaultvalueisfalse,meaningthatthecompletedatafromtheremotecollectionwillbetransferred.restrictCollections(string):anoptionalarrayofcollectionsforusewithrestrictType.IfrestrictTypeisinclude,onlythespecifiedcollectionswillbesychronised.IfrestrictTypeisexclude,allbutthespecifiedcollectionswillbesynchronized.password:thepasswordtousewhenconnectingtotheendpoint.
StartsafulldatasynchronizationfromaremoteendpointintothelocalArangoDBdatabase.
ReplicationDump
334
ThesyncmethodcanbeusedbyreplicationclientstoconnectanArangoDBdatabasetoaremoteendpoint,fetchtheremotelistofcollectionsandindexes,andcollectiondata.ItwillthuscreatealocalbackupofthestateofdataattheremoteArangoDBdatabase.syncworksonaper-databaselevel.
syncwillfirstfetchthelistofcollectionsandindexesfromtheremoteendpoint.ItdoessobycallingtheinventoryAPIoftheremotedatabase.ItwillthenpurgedatainthelocalArangoDBdatabase,andafterstartwilltransfercollectiondatafromtheremotedatabasetothelocalArangoDBdatabase.Itwillextractdatafromtheremotedatabasebycallingtheremotedatabase'sdumpAPIuntilalldataarefetched.
Incaseofsuccess,thebodyoftheresponseisaJSONobjectwiththefollowingattributes:
collections:anarrayofcollectionsthatweretransferredfromtheendpoint
lastLogTick:thelastlogtickontheendpointatthetimethetransferwasstarted.Usethisvalueasthefromvaluewhenstartingthecontinuoussynchronizationlater.
WARNING:callingthismethodwillsychronizedatafromthecollectionsfoundontheremoteendpointtothelocalArangoDBdatabase.Alldatainthelocalcollectionswillbepurgedandreplacedwithdatafromtheendpoint.
Usewithcaution!
Note:thismethodisnotsupportedonacoordinatorinacluster.
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.400:isreturnediftheconfigurationisincompleteormalformed.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredduringsychronization.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.
Returnclusterinventoryofcollectionsandindexes
retursanoverviewofcollectionsandindexesinacluster
GET/_api/replication/clusterInventory
QueryParameters
includeSystem(optional):Includesystemcollectionsintheresult.Thedefaultvalueistrue.
Returnsthearrayofcollectionsandindexesavailableonthecluster.
TheresponsewillbeanarrayofJSONobjects,oneforeachcollection.Eachcollectioncontainscontainsexactlytwokeys"parameters"and"indexes".ThisinformationcomesfromPlan/Collections/{DB-Name}/intheagency,justthattheindexes*attributethereisrelocatedtoadjustittothedataformatofarangodump.
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
ReplicationDump
335
ReplicationLoggerCommandsPreviousversionsofArangoDBallowedstarting,stoppingandconfiguringthereplicationlogger.ThesecommandsaresuperfluousinArangoDB2.2asalldata-modificationoperationsarewrittentotheserver'swrite-aheadlogandarenothandledbyaseparateloggeranymore.
TheonlyusefuloperationsremainingsinceArangoDB2.2aretoquerythecurrentstateoftheloggerandtofetchthelatestchangeswrittenbythelogger.Theoperationswillreturnthestateanddatafromthewrite-aheadlog.
Returnreplicationloggerstate
returnsthestateofthereplicationlogger
GET/_api/replication/logger-state
Returnsthecurrentstateoftheserver'sreplicationlogger.Thestatewillincludeinformationaboutwhethertheloggerisrunningandaboutthelastloggedtickvalue.Thistickvalueisimportantforincrementalfetchingofdata.
ThebodyoftheresponsecontainsaJSONobjectwiththefollowingattributes:
state:thecurrentloggerstateasaJSONobjectwiththefollowingsub-attributes:
running:whetherornottheloggerisrunning
lastLogTick:thetickvalueofthelatestticktheloggerhaslogged.Thisvaluecanbeusedforincrementalfetchingoflogdata.
totalEvents:totalnumberofeventsloggedsincetheserverwasstarted.Thevalueisnotresetbetweenmultiplestopsandre-startsofthelogger.
time:thecurrentdateandtimeontheloggerserver
server:aJSONobjectwiththefollowingsub-attributes:
version:theloggerserver'sversion
serverId:theloggerserver'sid
clients:returnsthelastfetchstatusbyreplicationclientsconnectedtothelogger.EachclientisreturnedasaJSONobjectwiththefollowingattributes:
serverId:serveridofclient
lastServedTick:lasttickvalueservedtothisclientviathelogger-followAPI
time:dateandtimewhenthisclientlastcalledthelogger-followAPI
Example:Returnsthestateofthereplicationlogger.
shell>curl--dump-http://localhost:8529/_api/replication/logger-state
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"state":{
"running":true,
"lastLogTick":"12090",
"lastUncommittedLogTick":"12090",
"totalEvents":4164,
"time":"2018-01-25T19:13:47Z"
},
"server":{
ReplicationLogger
336
"version":"3.3.3",
"serverId":"114837197342439"
},
"clients":[]
}
ReturnCodes
200:isreturnediftheloggerstatecouldbedeterminedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnediftheloggerstatecouldnotbedetermined.
Examples
Returnsthestateofthereplicationlogger.
shell>curl--dump-http://localhost:8529/_api/replication/logger-state
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyToquerythelatestchangesloggedbythereplicationlogger,theHTTPinterfacealsoprovidesthelogger-followmethod.
ThismethodshouldbeusedbyreplicationclientstoincrementallyfetchupdatesfromanArangoDBdatabase.
Returnslogentries
Fetchloglinesfromtheserver
GET/_api/replication/logger-follow
QueryParameters
from(optional):Lowerboundtickvalueforresults.to(optional):Upperboundtickvalueforresults.chunkSize(optional):Approximatemaximumsizeofthereturnedresult.includeSystem(optional):Includesystemcollectionsintheresult.Thedefaultvalueistrue.
Returnsdatafromtheserver'sreplicationlog.Thismethodcanbecalledbyreplicationclientsafteraninitialsynchronizationofdata.Themethodwillreturnall"recent"logentriesfromtheloggerserver,andtheclientscanreplayandapplytheseentrieslocallysotheygettothesamedatastateastheloggerserver.
Clientscancallthismethodrepeatedlytoincrementallyfetchallchangesfromtheloggerserver.Inthiscase,theyshouldprovidethefromvaluesotheywillonlygetreturnedthelogeventssincetheirlastfetch.
Whenthefromqueryparameterisnotused,theloggerserverwillreturnlogentriesstartingatthebeginningofitsreplicationlog.Whenthefromparameterisused,theloggerserverwillonlyreturnlogentrieswhichhavehighertickvaluesthanthespecifiedfromvalue(note:thelogentrywithatickvalueequaltofromwillbeexcluded).Usethefromvaluewhenincrementallyfetchinglogdata.
Thetoqueryparametercanbeusedtooptionallyrestricttheupperboundoftheresulttoacertaintickvalue.Ifused,theresultwillcontainonlylogeventswithtickvaluesupto(including)to.Inincrementalfetching,thereisnoneedtousethetoparameter.Itonlymakessenseinspecialsituations,whenonlypartsofthechangelogarerequired.
ThechunkSizequeryparametercanbeusedtocontrolthesizeoftheresult.Itmustbespecifiedinbytes.ThechunkSizevaluewillonlybehonoredapproximately.OtherwiseatoolowchunkSizevaluecouldcausetheservertonotbeabletoputjustonelogentryintotheresultandreturnit.Therefore,thechunkSizevaluewillonlybeconsultedafteralogentryhasbeenwrittenintotheresult.IftheresultsizeisthenbiggerthanchunkSize,theserverwillrespondwithasmanylogentriesasthereareintheresponsealready.IftheresultsizeisstillsmallerthanchunkSize,theserverwilltrytoreturnmoredataifthere'smoredatalefttoreturn.
IfchunkSizeisnotspecified,someserver-sidedefaultvaluewillbeused.
ReplicationLogger
337
TheContent-Typeoftheresultisapplication/x-arango-dump.Thisisaneasy-to-processformat,withalllogeventsgoingontoseparatelinesintheresponsebody.EachlogeventitselfisaJSONobject,withatleastthefollowingattributes:
tick:thelogeventtickvalue
type:thelogeventtype
Individuallogeventswillalsohaveadditionalattributes,dependingontheeventtype.Afewcommonattributeswhichareusedformultipleeventstypesare:
cid:idofthecollectiontheeventwasfor
tid:idofthetransactiontheeventwascontainedin
key:documentkey
rev:documentrevisionid
data:theoriginaldocumentdata
Amoredetaileddescriptionoftheindividualreplicationeventtypesandtheirdatastructurescanbefoundinthemanual.
TheresponsewillalsocontainthefollowingHTTPheaders:
x-arango-replication-active:whetherornottheloggerisactive.Clientscanusethisflagasanindicationfortheirpollingfrequency.Iftheloggerisnotactiveandtherearenomorereplicationeventsavailable,itmightbesensibleforaclienttoabort,ortogotosleepforalongtimeandtryagainlatertocheckwhethertheloggerhasbeenactivated.
x-arango-replication-lastincluded:thetickvalueofthelastincludedvalueintheresult.Inincrementallogfetching,thisvaluecanbeusedasthefromvalueforthefollowingrequest.Notethatiftheresultisempty,thevaluewillbe0.Thisvalueshouldnotbeusedasfromvaluebyclientsinthenextrequest(otherwisetheserverwouldreturnthelogeventsfromthestartofthelogagain).
x-arango-replication-lasttick:thelasttickvaluetheloggerserverhaslogged(notnecessarilyincludedintheresult).Bycomparingthethelasttickandlastincludedtickvalues,clientshaveanapproximateindicationofhowmanyeventstherearestilllefttofetch.
x-arango-replication-checkmore:whetherornottherealreadyexistsmorelogdatawhichtheclientcouldfetchimmediately.Ifthereismorelogdataavailable,theclientcouldcalllogger-followagainwithanadjustedfromvaluetofetchremaininglogentriesuntiltherearenomore.
Ifthereisn'tanymorelogdatatofetch,theclientmightdecidetogotosleepforawhilebeforecallingtheloggeragain.
Note:thismethodisnotsupportedonacoordinatorinacluster.
Example:Nologeventsavailable
shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?from=12070
HTTP/1.1204NoContent
x-arango-replication-lastincluded:0
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:false
x-arango-replication-frompresent:true
x-arango-replication-active:true
x-arango-replication-lasttick:12070
Example:Afewlogevents
shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?from=12070
ReplicationLogger
338
HTTP/1.1200OK
x-arango-replication-lastincluded:12090
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:false
x-arango-replication-frompresent:true
x-arango-replication-active:true
x-arango-replication-lasttick:12090
"{\"tick\":\"12072\",\"type\":2000,\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"allowUserKeys\":true
,\"cid\":\"12071\",\"count\":0,\"deleted\":false,\"doCompact\":true,\"globallyUniqueId\":\"h68719E5AC6E7/12071\",\"id\":\"12071
\",\"indexBuckets\":8,\"indexes\":[{\"fields\":[\"_key\"],\"id\":\"0\",\"selectivityEstimate\":1,\"sparse\":false,\"type\":\"pr
imary\",\"unique\":true}],\"isSmart\":false,\"isSystem\":false,\"isVolatile\":false,\"journalSize\":33554432,\"keyOptions\":{\"
allowUserKeys\":true,\"lastValue\":0,\"type\":\"traditional\"},\"name\":\"products\",\"numberOfShards\":1,\"planId\":\"12071\",
\"replicationFactor\":1,\"shardKeys\":[\"_key\"],\"shards\":{},\"status\":3,\"type\":2,\"version\":6,\"waitForSync\":false}}
{\"tick\":\"12076\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"_id\":\
"_unknown/p1\",\"_key\":\"p1\",\"_rev\":\"_WQ47eYu--_\",\"name\":\"fluxcompensator\"}}
{\"tick\":\"12078\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"_id\":\
"_unknown/p2\",\"_key\":\"p2\",\"_rev\":\"_WQ47eYu--B\",\"hp\":5100,\"name\":\"hybridhovercraft\"}}
{\"tick\":\"12080\",\"type\":2302,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"_key\":
\"p1\",\"_rev\":\"_WQ47eYu--D\"}}
{\"tick\":\"12082\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"_id\":\
"_unknown/p2\",\"_key\":\"p2\",\"_rev\":\"_WQ47eYy--_\",\"hp\":5100,\"name\":\"brokenhovercraft\"}}
{\"tick\":\"12083\",\"type\":2001,\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"cuid\":\"h68719E5AC6E
7/12071\",\"id\":\"12071\",\"name\":\"products\"}}
{\"tick\":\"12086\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"cname\":\"_users\",\"data\":{\"_id\":\"_user
s/10695\",\"_key\":\"10695\",\"_rev\":\"_WQ47eY6--_\",\"authData\":{\"active\":false,\"simple\":{\"hash\":\"1b3c695816f896d7d52
522b6e7fac12b1da668981aa95710ae1ab36828df87f7\",\"salt\":\"aa6d4cfe\",\"method\":\"sha256\"}},\"databases\":{},\"source\":\"COL
LECTION\",\"user\":\"tester\",\"userData\":{}}}
{\"tick\":\"12088\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"cname\":\"_users\",\"data\":{\"_id\":\"_user
s/89\",\"_key\":\"89\",\"_rev\":\"_WQ47eY6--B\",\"authData\":{\"active\":true,\"simple\":{\"hash\":\"90297fadeade5ffb0078e4f5aa
d32f22ab2180f11094b97794ac8a7326e2c30c\",\"salt\":\"a7522145\",\"method\":\"sha256\"}},\"databases\":{\"_system\":{\"permission
s\":{\"read\":true,\"write\":true},\"collections\":{\"*\":{\"permissions\":{\"read\":true,\"write\":true}}}},\"*\":{\"permissio
ns\":{\"read\":true,\"write\":true},\"collections\":{\"*\":{\"permissions\":{\"read\":true,\"write\":true}}}}},\"source\":\"COL
LECTION\",\"user\":\"root\"}}
{\"tick\":\"12090\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"cname\":\"_users\",\"data\":{\"_id\":\"_user
s/10683\",\"_key\":\"10683\",\"_rev\":\"_WQ47eY6--D\",\"authData\":{\"active\":true,\"simple\":{\"hash\":\"bfff9a16dea55c4d6ec7
5b595684c76f0a020aa239c2fb7fc633b8a094289fbb\",\"salt\":\"6e4298cb\",\"method\":\"sha256\"}},\"databases\":{},\"source\":\"COLL
ECTION\",\"user\":\"admin\",\"userData\":{}}}
"
Example:Moreeventsthanwouldfitintotheresponse
shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?from=12050&chunkSize=400
HTTP/1.1200OK
x-arango-replication-lastincluded:12052
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:true
x-arango-replication-frompresent:true
x-arango-replication-active:true
x-arango-replication-lasttick:12070
"{\"tick\":\"12052\",\"type\":2000,\"database\":\"1\",\"cid\":\"12051\",\"cname\":\"products\",\"data\":{\"allowUserKeys\":true
,\"cid\":\"12051\",\"count\":0,\"deleted\":false,\"doCompact\":true,\"globallyUniqueId\":\"h68719E5AC6E7/12051\",\"id\":\"12051
\",\"indexBuckets\":8,\"indexes\":[{\"fields\":[\"_key\"],\"id\":\"0\",\"selectivityEstimate\":1,\"sparse\":false,\"type\":\"pr
imary\",\"unique\":true}],\"isSmart\":false,\"isSystem\":false,\"isVolatile\":false,\"journalSize\":33554432,\"keyOptions\":{\"
allowUserKeys\":true,\"lastValue\":0,\"type\":\"traditional\"},\"name\":\"products\",\"numberOfShards\":1,\"planId\":\"12051\",
\"replicationFactor\":1,\"shardKeys\":[\"_key\"],\"shards\":{},\"status\":3,\"type\":2,\"version\":6,\"waitForSync\":false}}
"
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully,andtherearelogeventsavailablefortherequestedrange.Theresponsebodywillnotbeemptyinthiscase.204:isreturnediftherequestwasexecutedsuccessfully,buttherearenologeventsavailablefortherequestedrange.Theresponsebodywillbeemptyinthiscase.
ReplicationLogger
339
400:isreturnedifeitherthefromortovaluesareinvalid.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.
Examples
Nologeventsavailable
shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?from=12070
HTTP/1.1204NoContent
x-arango-replication-lastincluded:0
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:false
x-arango-replication-frompresent:true
x-arango-replication-active:true
x-arango-replication-lasttick:12070
Afewlogevents
shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?from=12070
HTTP/1.1200OK
x-arango-replication-lastincluded:12090
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:false
x-arango-replication-frompresent:true
x-arango-replication-active:true
x-arango-replication-lasttick:12090
"
{\"tick\":\"12072\",\"type\":2000,\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"product
s\",\"data\":
{\"allowUserKeys\":true,\"cid\":\"12071\",\"count\":0,\"deleted\":false,\"doCompact\":true
,\"globallyUniqueId\":\"h68719E5AC6E7/12071\",\"id\":\"12071\",\"indexBuckets\":8,\"indexe
s\":[{\"fields\":
[\"_key\"],\"id\":\"0\",\"selectivityEstimate\":1,\"sparse\":false,\"type\":\"primary\",\"
unique\":true}],\"isSmart\":false,\"isSystem\":false,\"isVolatile\":false,\"journalSize\":
33554432,\"keyOptions\":
{\"allowUserKeys\":true,\"lastValue\":0,\"type\":\"traditional\"},\"name\":\"products\",\"
numberOfShards\":1,\"planId\":\"12071\",\"replicationFactor\":1,\"shardKeys\":
[\"_key\"],\"shards\":
{},\"status\":3,\"type\":2,\"version\":6,\"waitForSync\":false}}\n{\"tick\":\"12076\",\"ty
pe\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data
\":{\"_id\":\"_unknown/p1\",\"_key\":\"p1\",\"_rev\":\"_WQ47eYu--_\",\"name\":\"flux
compensator\"}}\n{\"tick\":\"12078\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\
":\"12071\",\"cname\":\"products\",\"data\":
{\"_id\":\"_unknown/p2\",\"_key\":\"p2\",\"_rev\":\"_WQ47eYu--
B\",\"hp\":5100,\"name\":\"hybrid
hovercraft\"}}\n{\"tick\":\"12080\",\"type\":2302,\"tid\":\"0\",\"database\":\"1\",\"cid\"
:\"12071\",\"cname\":\"products\",\"data\":{\"_key\":\"p1\",\"_rev\":\"_WQ47eYu--
D\"}}\n{\"tick\":\"12082\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\
",\"cname\":\"products\",\"data\":
ReplicationLogger
340
{\"_id\":\"_unknown/p2\",\"_key\":\"p2\",\"_rev\":\"_WQ47eYy--
_\",\"hp\":5100,\"name\":\"broken
hovercraft\"}}\n{\"tick\":\"12083\",\"type\":2001,\"database\":\"1\",\"cid\":\"12071\",\"c
name\":\"products\",\"data\":
{\"cuid\":\"h68719E5AC6E7/12071\",\"id\":\"12071\",\"name\":\"products\"}}\n{\"tick\":\"12
086\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"cname\":\"_users\",\"
data\":{\"_id\":\"_users/10695\",\"_key\":\"10695\",\"_rev\":\"_WQ47eY6--_\",\"authData\":
{\"active\":false,\"simple\":
{\"hash\":\"1b3c695816f896d7d52522b6e7fac12b1da668981aa95710ae1ab36828df87f7\",\"salt\":\"
aa6d4cfe\",\"method\":\"sha256\"}},\"databases\":
{},\"source\":\"COLLECTION\",\"user\":\"tester\",\"userData\":
{}}}\n{\"tick\":\"12088\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"c
name\":\"_users\",\"data\":{\"_id\":\"_users/89\",\"_key\":\"89\",\"_rev\":\"_WQ47eY6--
B\",\"authData\":{\"active\":true,\"simple\":
{\"hash\":\"90297fadeade5ffb0078e4f5aad32f22ab2180f11094b97794ac8a7326e2c30c\",\"salt\":\"
a7522145\",\"method\":\"sha256\"}},\"databases\":{\"_system\":{\"permissions\":
{\"read\":true,\"write\":true},\"collections\":{\"*\":{\"permissions\":
{\"read\":true,\"write\":true}}}},\"*\":{\"permissions\":
{\"read\":true,\"write\":true},\"collections\":{\"*\":{\"permissions\":
{\"read\":true,\"write\":true}}}}},\"source\":\"COLLECTION\",\"user\":\"root\"}}\n{\"tick\
":\"12090\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"cname\":\"_user
s\",\"data\":{\"_id\":\"_users/10683\",\"_key\":\"10683\",\"_rev\":\"_WQ47eY6--
D\",\"authData\":{\"active\":true,\"simple\":
{\"hash\":\"bfff9a16dea55c4d6ec75b595684c76f0a020aa239c2fb7fc633b8a094289fbb\",\"salt\":\"
6e4298cb\",\"method\":\"sha256\"}},\"databases\":
{},\"source\":\"COLLECTION\",\"user\":\"admin\",\"userData\":{}}}\n"
Moreeventsthanwouldfitintotheresponse
shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?
from=12050&chunkSize=400
HTTP/1.1200OK
x-arango-replication-lastincluded:12052
x-content-type-options:nosniff
content-type:application/x-arango-dump;charset=utf-8
x-arango-replication-checkmore:true
x-arango-replication-frompresent:true
x-arango-replication-active:true
x-arango-replication-lasttick:12070
"
{\"tick\":\"12052\",\"type\":2000,\"database\":\"1\",\"cid\":\"12051\",\"cname\":\"product
s\",\"data\":
{\"allowUserKeys\":true,\"cid\":\"12051\",\"count\":0,\"deleted\":false,\"doCompact\":true
,\"globallyUniqueId\":\"h68719E5AC6E7/12051\",\"id\":\"12051\",\"indexBuckets\":8,\"indexe
s\":[{\"fields\":
[\"_key\"],\"id\":\"0\",\"selectivityEstimate\":1,\"sparse\":false,\"type\":\"primary\",\"
unique\":true}],\"isSmart\":false,\"isSystem\":false,\"isVolatile\":false,\"journalSize\":
33554432,\"keyOptions\":
{\"allowUserKeys\":true,\"lastValue\":0,\"type\":\"traditional\"},\"name\":\"products\",\"
numberOfShards\":1,\"planId\":\"12051\",\"replicationFactor\":1,\"shardKeys\":
[\"_key\"],\"shards\":{},\"status\":3,\"type\":2,\"version\":6,\"waitForSync\":false}}\n"
ReplicationLogger
341
Tocheckwhatrangeofchangesisavailable(identifiedbytickvalues),theHTTPinterfaceprovidesthemethodslogger-first-tickandlogger-tick-ranges.Replicationclientscanusethemethodstodetermineifcertaindata(identifiedbyatickdate)isstillavailableonthemaster.
Returnsthefirstavailabletickvalue
Returnthefirstavailabletickvaluefromtheserver
GET/_api/replication/logger-first-tick
Returnsthefirstavailabletickvaluethatcanbeservedfromtheserver'sreplicationlog.Thismethodcanbecalledbyreplicationclientsaftertodetermineifcertaindata(identifiedbyatickvalue)isstillavailableforreplication.
TheresultisaJSONobjectcontainingtheattributefirstTick.Thisattributecontainstheminimumtickvalueavailableintheserver'sreplicationlog.
Note:thismethodisnotsupportedonacoordinatorinacluster.
Example:Returningthefirstavailabletick
shell>curl--dump-http://localhost:8529/_api/replication/logger-first-tick
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
"{\"firstTick\":\"5\"}"
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.
Examples
Returningthefirstavailabletick
shell>curl--dump-http://localhost:8529/_api/replication/logger-first-tick
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
"{\"firstTick\":\"5\"}"
ReturnthetickrangesavailableintheWALlogfiles
returnsthetickvaluerangesavailableinthelogfiles
GET/_api/replication/logger-tick-ranges
ReturnsthecurrentlyavailablerangesoftickvaluesforallcurrentlyavailableWALlogfiles.Thetickvaluescanbeusedtodetermineifcertaindata(identifiedbytickvalue)arestillavailableforreplication.
ThebodyoftheresponsecontainsaJSONarray.Eacharraymemberisanobjectthatdescribesasinglelogfile.Eachobjecthasthefollowingattributes:
datafile:nameofthelogfile
ReplicationLogger
342
status:statusofthedatafile,intextualform(e.g."sealed","open")
tickMin:minimumtickvaluecontainedinlogfile
tickMax:maximumtickvaluecontainedinlogfile
Example:Returnstheavailabletickranges.
shell>curl--dump-http://localhost:8529/_api/replication/logger-tick-ranges
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-3.db",
"status":"collected",
"tickMin":"5",
"tickMax":"10381"
},
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-85.db",
"status":"collected",
"tickMin":"10397",
"tickMax":"10483"
},
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-86.db",
"status":"collected",
"tickMin":"10490",
"tickMax":"11986"
},
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-10384.db",
"status":"collected",
"tickMin":"11994",
"tickMax":"12003"
},
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-10486.db",
"status":"open",
"tickMin":"12009",
"tickMax":"12090"
}
]
ReturnCodes
200:isreturnedifthetickrangescouldbedeterminedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnediftheloggerstatecouldnotbedetermined.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.
Examples
Returnstheavailabletickranges.
shell>curl--dump-http://localhost:8529/_api/replication/logger-tick-ranges
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
ReplicationLogger
343
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-3.db",
"status":"collected",
"tickMin":"5",
"tickMax":"10381"
},
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-85.db",
"status":"collected",
"tickMin":"10397",
"tickMax":"10483"
},
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-86.db",
"status":"collected",
"tickMin":"10490",
"tickMax":"11986"
},
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-
10384.db",
"status":"collected",
"tickMin":"11994",
"tickMax":"12003"
},
{
"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-
10486.db",
"status":"open",
"tickMin":"12009",
"tickMax":"12090"
}
]
ReplicationLogger
344
ReplicationApplierCommandsTheappliercommandsallowtoremotelystart,stop,andquerythestateandconfigurationofanArangoDBdatabase'sreplicationapplier.
Returnconfigurationofreplicationapplier
fetchthecurrentreplicationconfiguration
GET/_api/replication/applier-config
Returnstheconfigurationofthereplicationapplier.
ThebodyoftheresponseisaJSONobjectwiththeconfiguration.Thefollowingattributesmaybepresentintheconfiguration:
endpoint:theloggerservertoconnectto(e.g."tcp://192.168.173.13:8529").
database:thenameofthedatabasetoconnectto(e.g."_system").
username:anoptionalArangoDBusernametousewhenconnectingtotheendpoint.
password:thepasswordtousewhenconnectingtotheendpoint.
maxConnectRetries:themaximumnumberofconnectionattemptstheapplierwillmakeinarow.Iftheappliercannotestablishaconnectiontotheendpointinthisnumberofattempts,itwillstopitself.
connectTimeout:thetimeout(inseconds)whenattemptingtoconnecttotheendpoint.Thisvalueisusedforeachconnectionattempt.
requestTimeout:thetimeout(inseconds)forindividualrequeststotheendpoint.
chunkSize:therequestedmaximumsizeforlogtransferpacketsthatisusedwhentheendpointiscontacted.
autoStart:whetherornottoauto-startthereplicationapplieron(nextandfollowing)serverstarts
adaptivePolling:whetherornotthereplicationapplierwilluseadaptivepolling.
includeSystem:whetherornotsystemcollectionoperationswillbeapplied
autoResync:whetherornottheslaveshouldperformafullautomaticresynchronizationwiththemasterincasethemastercannotservelogdatarequestedbytheslave,orwhenthereplicationisstartedandnotickvaluecanbefound.
autoResyncRetries:numberofresynchronizationretriesthatwillbeperformedinarowwhenautomaticresynchronizationisenabledandkicksin.Settingthisto0willeffectivelydisableautoResync.Settingittosomeothervaluewilllimitthenumberofretriesthatareperformed.Thishelpspreventingendlessretriesincaseresynchronizationsalwaysfail.
initialSyncMaxWaitTime:themaximumwaittime(inseconds)thattheinitialsynchronizationwillwaitforaresponsefromthemasterwhenfetchinginitialcollectiondata.Thiswaittimecanbeusedtocontrolafterwhattimetheinitialsynchronizationwillgiveupwaitingforaresponseandfail.ThisvalueisrelevantevenforcontinuousreplicationwhenautoResyncissettotruebecausethismayre-starttheinitialsynchronizationwhenthemastercannotprovidelogdatatheslaverequires.Thisvaluewillbeignoredifsetto0.
connectionRetryWaitTime:thetime(inseconds)thattheapplierwillintentionallyidlebeforeitretriesconnectingtothemasterincaseofconnectionproblems.Thisvaluewillbeignoredifsetto0.
idleMinWaitTime:theminimumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdata.ThiswaittimecanbeusedtocontrolthefrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemaster.Thisvaluewillbeignoredifsetto0.
idleMaxWaitTime:themaximumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdataandtherehavebeenpreviouslogfetchattemptsthatresultedinnomorelogdata.ThiswaittimecanbeusedtocontrolthemaximumfrequencywithwhichthereplicationappliersendsHTTPlogfetch
ReplicationApplier
345
requeststothemasterincasethereisnowriteactivityonthemasterforlongerperiods.ThisconfigurationvaluewillonlybeusediftheoptionadaptivePollingissettotrue.Thisvaluewillbeignoredifsetto0.
requireFromPresent:ifsettotrue,thenthereplicationapplierwillcheckatstartwhetherthestarttickfromwhichitstartsorresumesreplicationisstillpresentonthemaster.Ifnot,thentherewouldbedataloss.IfrequireFromPresentistrue,thereplicationapplierwillabortwithanappropriateerrormessage.Ifsettofalse,thenthereplicationapplierwillstillstart,andignorethedataloss.
verbose:ifsettotrue,thenaloglinewillbeemittedforalloperationsperformedbythereplicationapplier.Thisshouldbeusedfordebuggingreplicationproblemsonly.
restrictType:theconfigurationforrestrictCollections
restrictCollections:theoptionalarrayofcollectionstoincludeorexclude,basedonthesettingofrestrictType
Example:
shell>curl--dump-http://localhost:8529/_api/replication/applier-config
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"requestTimeout":600,
"connectTimeout":10,
"ignoreErrors":0,
"maxConnectRetries":100,
"lockTimeoutRetries":0,
"sslProtocol":0,
"chunkSize":0,
"skipCreateDrop":false,
"autoStart":false,
"adaptivePolling":true,
"autoResync":false,
"autoResyncRetries":2,
"includeSystem":true,
"requireFromPresent":false,
"verbose":false,
"incremental":false,
"restrictType":"",
"restrictCollections":[],
"connectionRetryWaitTime":15,
"initialSyncMaxWaitTime":300,
"idleMinWaitTime":1,
"idleMaxWaitTime":2.5,
"force32mode":false
}
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
Examples
shell>curl--dump-http://localhost:8529/_api/replication/applier-config
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
ReplicationApplier
346
Adjustconfigurationofreplicationapplier
setconfigurationvaluesofanapplier
PUT/_api/replication/applier-config
AJSONobjectwiththesepropertiesisrequired:
username:anoptionalArangoDBusernametousewhenconnectingtotheendpoint.includeSystem:whetherornotsystemcollectionoperationswillbeappliedendpoint:theloggerservertoconnectto(e.g."tcp://192.168.173.13:8529").Theendpointmustbespecified.verbose:ifsettotrue,thenaloglinewillbeemittedforalloperationsperformedbythereplicationapplier.Thisshouldbeusedfordebuggingreplicationproblemsonly.connectTimeout:thetimeout(inseconds)whenattemptingtoconnecttotheendpoint.Thisvalueisusedforeachconnectionattempt.autoResync:whetherornottheslaveshouldperformafullautomaticresynchronizationwiththemasterincasethemastercannotservelogdatarequestedbytheslave,orwhenthereplicationisstartedandnotickvaluecanbefound.database:thenameofthedatabaseontheendpoint.Ifnotspecified,defaultstothecurrentlocaldatabasename.idleMinWaitTime:theminimumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdata.ThiswaittimecanbeusedtocontrolthefrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemaster.Thisvaluewillbeignoredifsetto0.requestTimeout:thetimeout(inseconds)forindividualrequeststotheendpoint.requireFromPresent:ifsettotrue,thenthereplicationapplierwillcheckatstartwhetherthestarttickfromwhichitstartsorresumesreplicationisstillpresentonthemaster.Ifnot,thentherewouldbedataloss.IfrequireFromPresentistrue,thereplicationapplierwillabortwithanappropriateerrormessage.Ifsettofalse,thenthereplicationapplierwillstillstart,andignorethedataloss.idleMaxWaitTime:themaximumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdataandtherehavebeenpreviouslogfetchattemptsthatresultedinnomorelogdata.ThiswaittimecanbeusedtocontrolthemaximumfrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemasterforlongerperiods.ThisconfigurationvaluewillonlybeusediftheoptionadaptivePollingissettotrue.Thisvaluewillbeignoredifsetto0.restrictCollections(string):thearrayofcollectionstoincludeorexclude,basedonthesettingofrestrictTyperestrictType:theconfigurationforrestrictCollections;HastobeeitherincludeorexcludeinitialSyncMaxWaitTime:themaximumwaittime(inseconds)thattheinitialsynchronizationwillwaitforaresponsefromthemasterwhenfetchinginitialcollectiondata.Thiswaittimecanbeusedtocontrolafterwhattimetheinitialsynchronizationwillgiveupwaitingforaresponseandfail.ThisvalueisrelevantevenforcontinuousreplicationwhenautoResyncissettotruebecausethismayre-starttheinitialsynchronizationwhenthemastercannotprovidelogdatatheslaverequires.Thisvaluewillbeignoredifsetto0.maxConnectRetries:themaximumnumberofconnectionattemptstheapplierwillmakeinarow.Iftheappliercannotestablishaconnectiontotheendpointinthisnumberofattempts,itwillstopitself.autoStart:whetherornottoauto-startthereplicationapplieron(nextandfollowing)serverstartsadaptivePolling:ifsettotrue,thereplicationapplierwillfalltosleepforanincreasinglylongperiodincasetheloggerserverattheendpointdoesnothaveanymorereplicationeventstoapply.Usingadaptivepollingisthususefultoreducetheamountofworkforboththeapplierandtheloggerserverforcaseswhenthereareonlyinfrequentchanges.Thedownsideisthatwhenusingadaptivepolling,itmighttakelongerforthereplicationappliertodetectthattherearenewreplicationeventsontheloggerserver.SettingadaptivePollingtofalsewillmakethereplicationappliercontacttheloggerserverinaconstantinterval,regardlessofwhethertheloggerserverprovidesupdatesfrequentlyorseldom.password:thepasswordtousewhenconnectingtotheendpoint.connectionRetryWaitTime:thetime(inseconds)thattheapplierwillintentionallyidlebeforeitretriesconnectingtothemasterincaseofconnectionproblems.Thisvaluewillbeignoredifsetto0.autoResyncRetries:numberofresynchronizationretriesthatwillbeperformedinarowwhenautomaticresynchronizationisenabledandkicksin.Settingthisto0willeffectivelydisableautoResync.Settingittosomeothervaluewilllimitthenumberofretriesthatareperformed.Thishelpspreventingendlessretriesincaseresynchronizationsalwaysfail.chunkSize:therequestedmaximumsizeforlogtransferpacketsthatisusedwhentheendpointiscontacted.
Setstheconfigurationofthereplicationapplier.Theconfigurationcanonlybechangedwhiletheapplierisnotrunning.Theupdatedconfigurationwillbesavedimmediatelybutonlybecomeactivewiththenextstartoftheapplier.
ReplicationApplier
347
Incaseofsuccess,thebodyoftheresponseisaJSONobjectwiththeupdatedconfiguration.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/replication/applier-config<<EOF
{
"endpoint":"tcp://127.0.0.1:8529",
"username":"replicationApplier",
"password":"applier1234@foxx",
"chunkSize":4194304,
"autoStart":false,
"adaptivePolling":true
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"endpoint":"tcp://127.0.0.1:8529",
"database":"_system",
"username":"replicationApplier",
"requestTimeout":600,
"connectTimeout":10,
"ignoreErrors":0,
"maxConnectRetries":100,
"lockTimeoutRetries":0,
"sslProtocol":0,
"chunkSize":4194304,
"skipCreateDrop":false,
"autoStart":false,
"adaptivePolling":true,
"autoResync":false,
"autoResyncRetries":2,
"includeSystem":true,
"requireFromPresent":false,
"verbose":false,
"incremental":false,
"restrictType":"",
"restrictCollections":[],
"connectionRetryWaitTime":15,
"initialSyncMaxWaitTime":300,
"idleMinWaitTime":1,
"idleMaxWaitTime":2.5,
"force32mode":false
}
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.400:isreturnediftheconfigurationisincompleteormalformed,orifthereplicationapplieriscurrentlyrunning.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
Examples
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/replication/applier-config<<EOF
{
"endpoint":"tcp://127.0.0.1:8529",
"username":"replicationApplier",
"password":"applier1234@foxx",
"chunkSize":4194304,
"autoStart":false,
"adaptivePolling":true
ReplicationApplier
348
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Startreplicationapplier
startthereplicationapplier
PUT/_api/replication/applier-start
QueryParameters
from(optional):TheremotelastLogTickvaluefromwhichtostartapplying.Ifnotspecified,thelastsavedtickfromthepreviousapplierrunisused.Ifthereisnopreviousapplierstatesaved,theapplierwillstartatthebeginningoftheloggerserver'slog.
Startsthereplicationapplier.Thiswillreturnimmediatelyifthereplicationapplierisalreadyrunning.
Ifthereplicationapplierisnotalreadyrunning,theapplierconfigurationwillbechecked,andifitiscomplete,theapplierwillbestartedinabackgroundthread.Thismeansthateveniftheapplierwillencounteranyerrorswhilerunning,theywillnotbereportedintheresponsetothismethod.
Todetectreplicationappliererrorsaftertheapplierwasstarted,usethe/_api/replication/applier-stateAPIinstead.
Example:
shell>curl-XPUT--dump-http://localhost:8529/_api/replication/applier-start
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"state":{
"running":true,
"lastAppliedContinuousTick":null,
"lastProcessedContinuousTick":null,
"lastAvailableContinuousTick":null,
"safeResumeTick":null,
"progress":{
"time":"2018-01-25T19:13:18Z",
"message":"applierinitiallycreatedfordatabase'_system'",
"failedConnects":0
},
"totalRequests":0,
"totalFailedConnects":0,
"totalEvents":0,
"totalResyncs":0,
"totalOperationsExcluded":0,
"lastError":{
"errorNum":0
},
"time":"2018-01-25T19:13:41Z"
},
"server":{
"version":"3.3.3",
"serverId":"114837197342439"
},
"endpoint":"tcp://127.0.0.1:8529",
"database":"_system"
}
ReplicationApplier
349
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.400:isreturnedifthereplicationapplierisnotfullyconfiguredortheconfigurationisinvalid.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
Examples
shell>curl-XPUT--dump-http://localhost:8529/_api/replication/applier-start
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Stopreplicationapplier
stopthereplication
PUT/_api/replication/applier-stop
Stopsthereplicationapplier.Thiswillreturnimmediatelyifthereplicationapplierisnotrunning.
Example:
shell>curl-XPUT--dump-http://localhost:8529/_api/replication/applier-stop
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"state":{
"running":false,
"lastAppliedContinuousTick":null,
"lastProcessedContinuousTick":null,
"lastAvailableContinuousTick":null,
"safeResumeTick":null,
"progress":{
"time":"2018-01-25T19:13:43Z",
"message":"appliershutdown",
"failedConnects":0
},
"totalRequests":6,
"totalFailedConnects":3,
"totalEvents":0,
"totalResyncs":0,
"totalOperationsExcluded":0,
"lastError":{
"errorNum":0
},
"time":"2018-01-25T19:13:43Z"
},
"server":{
"version":"3.3.3",
"serverId":"114837197342439"
},
"endpoint":"tcp://127.0.0.1:8529",
"database":"_system"
}
ReturnCodes
ReplicationApplier
350
200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
Examples
shell>curl-XPUT--dump-http://localhost:8529/_api/replication/applier-stop
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Stateofthereplicationapplier
outputthecurrentstatusofthereplication
GET/_api/replication/applier-state
Returnsthestateofthereplicationapplier,regardlessofwhethertheapplieriscurrentlyrunningornot.
TheresponseisaJSONobjectwiththefollowingattributes:
state:aJSONobjectwiththefollowingsub-attributes:
running:whetherornottheapplierisactiveandrunning
lastAppliedContinuousTick:thelasttickvaluefromthecontinuousreplicationlogtheapplierhasapplied.
lastProcessedContinuousTick:thelasttickvaluefromthecontinuousreplicationlogtheapplierhasprocessed.
Regularly,thelastappliedandlastprocessedtickvaluesshouldbeidentical.Fortransactionaloperations,thereplicationapplierwillfirstprocessincominglogeventsbeforeapplyingthem,sotheprocessedtickvaluemightbehigherthantheappliedtickvalue.Thiswillbethecaseuntiltheapplierencountersthetransactioncommitlogeventforthetransaction.
lastAvailableContinuousTick:thelasttickvaluetheloggerservercanprovide.
time:thetimeontheapplierserver.
totalRequests:thetotalnumberofrequeststheapplierhasmadetotheendpoint.
totalFailedConnects:thetotalnumberoffailedconnectionattemptstheapplierhasmade.
totalEvents:thetotalnumberoflogeventstheapplierhasprocessed.
totalOperationsExcluded:thetotalnumberoflogeventsexcludedbecauseofrestrictCollections.
progress:aJSONobjectwithdetailsaboutthereplicationapplierprogress.Itcontainsthefollowingsub-attributesifthereisprogresstoreport:
message:atextualdescriptionoftheprogress
time:thedateandtimetheprogresswaslogged
failedConnects:thecurrentnumberoffailedconnectionattempts
lastError:aJSONobjectwithdetailsaboutthelasterrorthathappenedontheapplier.Itcontainsthefollowingsub-attributesiftherewasanerror:
errorNum:anumericalerrorcode
errorMessage:atextualerrordescription
time:thedateandtimetheerroroccurred
Incasenoerrorhasoccurred,lastErrorwillbeempty.
ReplicationApplier
351
server:aJSONobjectwiththefollowingsub-attributes:
version:theapplierserver'sversion
serverId:theapplierserver'sid
endpoint:theendpointtheapplierisconnectedto(ifapplierisactive)orwillconnectto(ifapplieriscurrentlyinactive)
database:thenameofthedatabasetheapplierisconnectedto(ifapplierisactive)orwillconnectto(ifapplieriscurrentlyinactive)
Example:Fetchingthestateofaninactiveapplier:
shell>curl--dump-http://localhost:8529/_api/replication/applier-state
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"state":{
"running":false,
"lastAppliedContinuousTick":null,
"lastProcessedContinuousTick":null,
"lastAvailableContinuousTick":null,
"safeResumeTick":null,
"progress":{
"time":"2018-01-25T19:13:42Z",
"message":"appliershutdown",
"failedConnects":1
},
"totalRequests":2,
"totalFailedConnects":1,
"totalEvents":0,
"totalResyncs":0,
"totalOperationsExcluded":0,
"lastError":{
"errorNum":0
},
"time":"2018-01-25T19:13:42Z"
},
"server":{
"version":"3.3.3",
"serverId":"114837197342439"
},
"endpoint":"tcp://127.0.0.1:8529",
"database":"_system"
}
Example:Fetchingthestateofanactiveapplier:
shell>curl--dump-http://localhost:8529/_api/replication/applier-state
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"state":{
"running":true,
"lastAppliedContinuousTick":null,
"lastProcessedContinuousTick":null,
"lastAvailableContinuousTick":null,
"safeResumeTick":null,
"progress":{
ReplicationApplier
352
"time":"2018-01-25T19:13:42Z",
"message":"fetchingmasterstateinformation",
"failedConnects":0
},
"totalRequests":2,
"totalFailedConnects":1,
"totalEvents":0,
"totalResyncs":0,
"totalOperationsExcluded":0,
"lastError":{
"errorNum":0
},
"time":"2018-01-25T19:13:42Z"
},
"server":{
"version":"3.3.3",
"serverId":"114837197342439"
},
"endpoint":"tcp://127.0.0.1:8529",
"database":"_system"
}
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
Examples
Fetchingthestateofaninactiveapplier:
shell>curl--dump-http://localhost:8529/_api/replication/applier-state
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyFetchingthestateofanactiveapplier:
shell>curl--dump-http://localhost:8529/_api/replication/applier-state
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Turntheserverintoaslaveofanother
Changesroletoslave
PUT/_api/replication/make-slave
AJSONobjectwiththesepropertiesisrequired:
username:anoptionalArangoDBusernametousewhenconnectingtothemaster.includeSystem:whetherornotsystemcollectionoperationswillbeappliedendpoint:themasterendpointtoconnectto(e.g."tcp://192.168.173.13:8529").verbose:ifsettotrue,thenaloglinewillbeemittedforalloperationsperformedbythereplicationapplier.Thisshouldbeusedfordebuggingreplicationproblemsonly.
ReplicationApplier
353
connectTimeout:thetimeout(inseconds)whenattemptingtoconnecttotheendpoint.Thisvalueisusedforeachconnectionattempt.autoResync:whetherornottheslaveshouldperformanautomaticresynchronizationwiththemasterincasethemastercannotservelogdatarequestedbytheslave,orwhenthereplicationisstartedandnotickvaluecanbefound.database:thedatabasenameonthemaster(ifnotspecified,defaultstothenameofthelocalcurrentdatabase).idleMinWaitTime:theminimumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdata.ThiswaittimecanbeusedtocontrolthefrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemaster.Thisvaluewillbeignoredifsetto0.requestTimeout:thetimeout(inseconds)forindividualrequeststotheendpoint.restrictType:anoptionalstringvalueforcollectionfiltering.Whenspecified,theallowedvaluesareincludeorexclude.idleMaxWaitTime:themaximumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdataandtherehavebeenpreviouslogfetchattemptsthatresultedinnomorelogdata.ThiswaittimecanbeusedtocontrolthemaximumfrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemasterforlongerperiods.ThisconfigurationvaluewillonlybeusediftheoptionadaptivePollingissettotrue.Thisvaluewillbeignoredifsetto0.initialSyncMaxWaitTime:themaximumwaittime(inseconds)thattheinitialsynchronizationwillwaitforaresponsefromthemasterwhenfetchinginitialcollectiondata.Thiswaittimecanbeusedtocontrolafterwhattimetheinitialsynchronizationwillgiveupwaitingforaresponseandfail.ThisvalueisrelevantevenforcontinuousreplicationwhenautoResyncissettotruebecausethismayre-starttheinitialsynchronizationwhenthemastercannotprovidelogdatatheslaverequires.Thisvaluewillbeignoredifsetto0.restrictCollections(string):anoptionalarrayofcollectionsforusewithrestrictType.IfrestrictTypeisinclude,onlythespecifiedcollectionswillbesychronised.IfrestrictTypeisexclude,allbutthespecifiedcollectionswillbesynchronized.requireFromPresent:ifsettotrue,thenthereplicationapplierwillcheckatstartofitscontinuousreplicationifthestarttickfromthedumpphaseisstillpresentonthemaster.Ifnot,thentherewouldbedataloss.IfrequireFromPresentistrue,thereplicationapplierwillabortwithanappropriateerrormessage.Ifsettofalse,thenthereplicationapplierwillstillstart,andignorethedataloss.adaptivePolling:whetherornotthereplicationapplierwilluseadaptivepolling.maxConnectRetries:themaximumnumberofconnectionattemptstheapplierwillmakeinarow.Iftheappliercannotestablishaconnectiontotheendpointinthisnumberofattempts,itwillstopitself.password:thepasswordtousewhenconnectingtothemaster.connectionRetryWaitTime:thetime(inseconds)thattheapplierwillintentionallyidlebeforeitretriesconnectingtothemasterincaseofconnectionproblems.Thisvaluewillbeignoredifsetto0.autoResyncRetries:numberofresynchronizationretriesthatwillbeperformedinarowwhenautomaticresynchronizationisenabledandkicksin.Settingthisto0willeffectivelydisableautoResync.Settingittosomeothervaluewilllimitthenumberofretriesthatareperformed.Thishelpspreventingendlessretriesincaseresynchronizationsalwaysfail.chunkSize:therequestedmaximumsizeforlogtransferpacketsthatisusedwhentheendpointiscontacted.
StartsafulldatasynchronizationfromaremoteendpointintothelocalArangoDBdatabaseandafterwardsstartsthecontinuousreplication.Theoperationworksonaper-databaselevel.
Alllocaldatabasedatawillberemovedpriortothesynchronization.
Incaseofsuccess,thebodyoftheresponseisaJSONobjectwiththefollowingattributes:
state:aJSONobjectwiththefollowingsub-attributes:
running:whetherornottheapplierisactiveandrunning
lastAppliedContinuousTick:thelasttickvaluefromthecontinuousreplicationlogtheapplierhasapplied.
lastProcessedContinuousTick:thelasttickvaluefromthecontinuousreplicationlogtheapplierhasprocessed.
Regularly,thelastappliedandlastprocessedtickvaluesshouldbeidentical.Fortransactionaloperations,thereplicationapplierwillfirstprocessincominglogeventsbeforeapplyingthem,sotheprocessedtickvaluemightbehigherthantheappliedtickvalue.Thiswillbethecaseuntiltheapplierencountersthetransactioncommitlogeventforthetransaction.
lastAvailableContinuousTick:thelasttickvaluetheloggerservercanprovide.
time:thetimeontheapplierserver.
ReplicationApplier
354
totalRequests:thetotalnumberofrequeststheapplierhasmadetotheendpoint.
totalFailedConnects:thetotalnumberoffailedconnectionattemptstheapplierhasmade.
totalEvents:thetotalnumberoflogeventstheapplierhasprocessed.
totalOperationsExcluded:thetotalnumberoflogeventsexcludedbecauseofrestrictCollections.
progress:aJSONobjectwithdetailsaboutthereplicationapplierprogress.Itcontainsthefollowingsub-attributesifthereisprogresstoreport:
message:atextualdescriptionoftheprogress
time:thedateandtimetheprogresswaslogged
failedConnects:thecurrentnumberoffailedconnectionattempts
lastError:aJSONobjectwithdetailsaboutthelasterrorthathappenedontheapplier.Itcontainsthefollowingsub-attributesiftherewasanerror:
errorNum:anumericalerrorcode
errorMessage:atextualerrordescription
time:thedateandtimetheerroroccurred
Incasenoerrorhasoccurred,lastErrorwillbeempty.
server:aJSONobjectwiththefollowingsub-attributes:
version:theapplierserver'sversion
serverId:theapplierserver'sid
endpoint:theendpointtheapplierisconnectedto(ifapplierisactive)orwillconnectto(ifapplieriscurrentlyinactive)
database:thenameofthedatabasetheapplierisconnectedto(ifapplierisactive)orwillconnectto(ifapplieriscurrentlyinactive)
WARNING:callingthismethodwillsychronizedatafromthecollectionsfoundontheremotemastertothelocalArangoDBdatabase.Alldatainthelocalcollectionswillbepurgedandreplacedwithdatafromthemaster.
Usewithcaution!
Pleasealsokeepinmindthatthiscommandmaytakealongtimetocompleteandreturn.Thisisbecauseitwillfirstdoafulldatasynchronizationwiththemaster,whichwilltaketimeroughlyproportionaltotheamountofdata.
Note:thismethodisnotsupportedonacoordinatorinacluster.
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.400:isreturnediftheconfigurationisincompleteormalformed.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredduringsychronizationorwhenstartingthecontinuousreplication.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.
ReplicationApplier
355
OtherReplicationCommands
Returnserverid
fetchthisserver'suniqueidentifier
GET/_api/replication/server-id
Returnstheserversid.TheidisalsoreturnedbyotherreplicationAPImethods,andthismethodisaneasymeansofdeterminingaserver'sid.
ThebodyoftheresponseisaJSONobjectwiththeattributeserverId.Theserveridisreturnedasastring.
Example:
shell>curl--dump-http://localhost:8529/_api/replication/server-id
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"serverId":"114837197342439"
}
ReturnCodes
200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.
Examples
shell>curl--dump-http://localhost:8529/_api/replication/server-id
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"serverId":"114837197342439"
}
OtherReplicationCommands
356
HTTPInterfaceforShardingShardingonlyshouldbeusedbydevelopers!
Executeclusterroundtrip
executesaclusterroundtripforsharding
GET/_admin/cluster-test
ExecutesaclusterroundtripfromacoordinatortoaDBserverandback.Thiscallonlyworksinacoordinatornodeinacluster.OnecanandshouldappendanarbitrarypathtotheURLandthepartafter/_admin/cluster-testisusedasthepathoftheHTTPrequestwhichissentfromthecoordinatortoaDBnode.Likewise,anyformdataappendedtotheURLisforwardedintherequesttotheDBnode.Thishandlertakescareofallrequesttypes(seebelow)andusesthesamerequesttypeinitsrequesttotheDBnode.
ThefollowingHTTPheadersareinterpretedinaspecialway:
X-Shard-ID:ThisspecifiestheIDoftheshardtowhichtheclusterrequestissentandthustellsthesystemtowhichDBservertosendtheclusterrequest.NotethatthemappingfromtheshardIDtotheresponsibleserverhastobedefinedintheagencyunderCurrent/ShardLocation/.Onehastogivethisheader,otherwisethesystemdoesnotknowwheretosendtherequest.X-Client-Transaction-ID:thevalueofthisheaderistakenastheclienttransactionIDfortherequestX-Timeout:specifiesatimeoutinsecondsfortheclusteroperation.Iftheanswerdoesnotarrivewithinthespecifiedtimeout,ancorrespondingerrorisreturnedandanysubsequentrealanswerisignored.Thedefaultifnotgivenis24hours.X-Synchronous-Mode:Ifsettotruethetestfunctionusessynchronousmode,otherwisethedefaultasynchronousoperationmodeisused.Thisismainlyfordebuggingpurposes.Host:ThisheaderisignoredandnotforwardedtotheDBserver.User-Agent:ThisheaderisignoredandnotforwardedtotheDBserver.
AllotherHTTPheadersandthebodyoftherequest(ifpresent,seeotherHTTPmethodsbelow)areforwardedasgivenintheoriginalrequest.
InasynchronousmodetheDBserveranswerswithanHTTPrequestofitsown,insynchronousmodeitsendsaHTTPresponse.InbothcasestheheadersandthebodyareusedtoproducetheHTTPresponseofthisAPIcall.
ReturnCodes
Thereturncodecanbeanythingtheclusterrequestreturns,aswellas:
200:isreturnedwheneverythingwentwell,orifatimeoutoccurred.Inthelattercaseabodyoftypeapplication/jsonindicatingthetimeoutisreturned.403:isreturnedifArangoDBisnotrunninginclustermode.404:isreturnedifArangoDBwasnotcompiledforclusteroperation.
Executeclusterroundtrip
executesaclusterroundtripforsharding
POST/_admin/cluster-test
RequestBody(required)
Thebodycanbeanytypeandissimplyforwarded.
SeeGETmethod.
Executeclusterroundtrip
executesaclusterroundtripforsharding
PUT/_admin/cluster-test
RequestBody(required)
Sharding
357
SeeGETmethod.Thebodycanbeanytypeandissimplyforwarded.
Deleteclusterroundtrip
executesaclusterroundtripforsharding
DELETE/_admin/cluster-test
SeeGETmethod.
Updateclusterroundtrip
executesaclusterroundtripforsharding
PATCH/_admin/cluster-test
RequestBody(required)
SeeGETmethod.Thebodycanbeanytypeandissimplyforwarded.
Executeclusterroundtrip
executesaclusterroundtripforsharding
HEAD/_admin/cluster-test
SeeGETmethod.
Checkport
allowstocheckwhetheragivenportisusable
GET/_admin/clusterCheckPort
QueryParameters
port(required):
ReturnCodes
200:isreturnedwheneverythingwentwell.400:theparameterportwasnotgivenorisnointeger.
Sharding
358
HTTPInterfaceforAdministrationandMonitoringThisisanintroductiontoArangoDB'sHTTPinterfaceforadministrationandmonitoringoftheserver.
Readgloballogsfromtheserver
returnstheserverlogs
GET/_admin/log
QueryParameters
upto(optional):Returnsalllogentriesuptologlevelupto.Notethatuptomustbe:fatalor0erroror1warningor2infoor3debugor4Thedefaultvalueisinfo.level(optional):Returnsalllogentriesofloglevellevel.Notethatthequeryparametersuptoandlevelaremutuallyexclusive.start(optional):Returnsalllogentriessuchthattheirlogentryidentifier(lidvalue)isgreaterorequaltostart.size(optional):Restrictstheresulttoatmostsizelogentries.offset(optional):Startstoreturnlogentriesskippingthefirstoffsetlogentries.offsetandsizecanbeusedforpagination.search(optional):Onlyreturnthelogentriescontainingthetextspecifiedinsearch.sort(optional):Sortthelogentrieseitherascending(ifsortisasc)ordescending(ifsortisdesc)accordingtotheirlidvalues.Notethatthelidimposesachronologicalorder.Thedefaultvalueisasc.
Returnsfatal,error,warningorinfologmessagesfromtheserver'sgloballog.TheresultisaJSONobjectwiththefollowingattributes:
AjsondocumentwiththesePropertiesisreturned:
HTTP200
lid(string):alistoflogentryidentifiers.Eachlogmessageisuniquelyidentifiedbyits@LIT{lid}andtheidentifiersareinascendingorder.level:Alistoftheloglevelsforalllogentries.timestamp(string):alistofthetimestampsassecondssince1970-01-01foralllogentries.topic:alistofthetopicsofalllogentriestext:alistofthetextsofalllogentriestotalAmount:thetotalamountoflogentriesbeforepagination.
ReturnCodes
200:
ResponseBody
lid(string):alistoflogentryidentifiers.Eachlogmessageisuniquelyidentifiedbyits@LIT{lid}andtheidentifiersareinascendingorder.-level:Alistoftheloglevelsforalllogentries.text:alistofthetextsofalllogentriestopic:alistofthetopicsofalllogentriestimestamp(string):alistofthetimestampsassecondssince1970-01-01foralllogentries.-totalAmount:thetotalamountoflogentriesbeforepagination.
Returnthecurrentserverloglevel
returnsthecurrentloglevelsettings
GET/_admin/log/level
Monitoring
359
Returnstheserver'scurrentloglevelsettings.TheresultisaJSONobjectwiththelogtopicsbeingtheobjectkeys,andtheloglevelsbeingtheobjectvalues.
ReturnCodes
200:isreturnediftherequestisvalid500:isreturnediftheservercannotgeneratetheresultduetoanout-of-memoryerror.
Modifyandreturnthecurrentserverloglevel
modifiesthecurrentloglevelsettings
PUT/_admin/log/level
Modifiesandreturnstheserver'scurrentloglevelsettings.TherequestbodymustbeaJSONobjectwiththelogtopicsbeingtheobjectkeysandtheloglevelsbeingtheobjectvalues.
TheresultisaJSONobjectwiththeadjustedlogtopicsbeingtheobjectkeys,andtheadjustedloglevelsbeingtheobjectvalues.
Itcansettheloglevelofallfacilitiesbyonlyspecifyingtheloglevelasstringwithoutjson.
Possibleloglevelsare:
FATAL-Therewillbenowayoutofthis.ArangoDBwillgodownafterthismessage.ERROR-Thisisanerror.youshouldinvestigateandfixit.Itmayharmyourproduction.WARNING-Thismaybeseriousapplication-wise,butwedon'tknow.INFO-Somethinghashappened,takenotice,butnodramaattached.DEBUG-outputdebugmessagesTRACE-trace-prepareyourlogtobeflooded-don'tuseinproduction.
AJSONobjectwiththesepropertiesisrequired:
audit-service:Oneofthepossibleloglevels.cache:Oneofthepossibleloglevels.syscall:Oneofthepossibleloglevels.communication:Oneofthepossibleloglevels.audit-authentication:Oneofthepossibleloglevels.agencycomm:Oneofthepossibleloglevels.startup:Oneofthepossibleloglevels.general:Oneofthepossibleloglevels.cluster:Oneofthepossibleloglevels.audit-view:Oneofthepossibleloglevels.collector:Oneofthepossibleloglevels.audit-documentation:Oneofthepossibleloglevels.engines:Oneofthepossibleloglevels.trx:Oneofthepossibleloglevels.mmap:Oneofthepossibleloglevels.agency:Oneofthepossibleloglevels.authentication:Oneofthepossibleloglevels.memory:Oneofthepossibleloglevels.performance:Oneofthepossibleloglevels.config:Oneofthepossibleloglevels.authorization:Oneofthepossibleloglevels.development:Oneofthepossibleloglevels.datafiles:Oneofthepossibleloglevels.views:Oneofthepossibleloglevels.ldap:Oneofthepossibleloglevels.replication:Oneofthepossibleloglevels.threads:Oneofthepossibleloglevels.audit-database:Oneofthepossibleloglevels.v8:Oneofthepossibleloglevels.
Monitoring
360
ssl:Oneofthepossibleloglevels.pregel:Oneofthepossibleloglevels.audit-collection:Oneofthepossibleloglevels.rocksdb:Oneofthepossibleloglevels.supervision:Oneofthepossibleloglevels.graphs:Oneofthepossibleloglevels.compactor:Oneofthepossibleloglevels.queries:Oneofthepossibleloglevels.heartbeat:Oneofthepossibleloglevels.requests:Oneofthepossibleloglevels.
ReturnCodes
200:isreturnediftherequestisvalid400:isreturnedwhentherequestbodycontainsinvalidJSON.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnediftheservercannotgeneratetheresultduetoanout-of-memoryerror.
Reloadstheroutinginformation
Reloadtheroutingtable.
POST/_admin/routing/reload
Reloadstheroutinginformationfromthecollectionrouting.
ReturnCodes
200:Routinginformationwasreloadedsuccessfully.
Readthestatistics
returnthestatisticsinformation
GET/_admin/statistics
Returnsthestatisticsinformation.Thereturnedobjectcontainsthestatisticsfiguresgroupedtogetheraccordingtothedescriptionreturnedby_admin/statistics-description.Forinstance,toaccessafigureuserTimefromthegroupsystem,youfirstselectthesub-objectdescribingthegroupstoredinsystemandinthatsub-objectthevalueforuserTimeisstoredintheattributeofthesamename.
Incaseofadistribution,thereturnedobjectcontainsthetotalcountincountandthedistributionlistincounts.Thesum(ortotal)oftheindividualvaluesisreturnedinsum.
Example:
shell>curl--dump-http://localhost:8529/_admin/statistics
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"time":1516907617.8872316,
"enabled":true,
"system":{
"minorPageFaults":76569,
"majorPageFaults":183,
"userTime":2.21,
"systemTime":0.49,
"numberOfThreads":48,
"residentSize":426942464,
"residentSizePercent":0.02556949617048751,
"virtualSize":3208433664
},
"client":{
Monitoring
361
"httpConnections":1,
"connectionTime":{
"sum":0,
"count":0,
"counts":[
0,
0,
0,
0
]
},
"totalTime":{
"sum":12.890824556350708,
"count":4034,
"counts":[
3799,
145,
76,
10,
4,
0,
0
]
},
"requestTime":{
"sum":0.030986785888671875,
"count":4034,
"counts":[
4033,
1,
0,
0,
0,
0,
0
]
},
"queueTime":{
"sum":0.0002090930938720703,
"count":9,
"counts":[
9,
0,
0,
0,
0,
0,
0
]
},
"ioTime":{
"sum":12.859628677368164,
"count":4034,
"counts":[
3800,
144,
76,
10,
4,
0,
0
]
},
"bytesSent":{
"sum":1794760,
"count":4034,
"counts":[
304,
3392,
319,
19,
0,
0
]
},
"bytesReceived":{
Monitoring
362
"sum":871054,
"count":4034,
"counts":[
3727,
307,
0,
0,
0,
0
]
}
},
"http":{
"requestsTotal":4034,
"requestsAsync":9,
"requestsGet":1019,
"requestsHead":0,
"requestsPost":2794,
"requestsPut":70,
"requestsPatch":3,
"requestsDelete":148,
"requestsOptions":0,
"requestsOther":0
},
"server":{
"uptime":19.03903317451477,
"physicalMemory":16697335808,
"v8Context":{
"available":4,
"busy":4,
"dirty":0,
"free":0,
"max":16
},
"threads":{
"running":8,
"working":4,
"blocked":0,
"queued":4
}
},
"error":false,
"code":200
}
ReturnCodes
200:Statisticswerereturnedsuccessfully.
Examples
shell>curl--dump-http://localhost:8529/_admin/statistics
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Statisticsdescription
fetchdescriptiveinfoofstatistics
GET/_admin/statistics-description
Returnsadescriptionofthestatisticsreturnedby/_admin/statistics.Thereturnedobjectscontainsanarrayofstatisticsgroupsintheattributegroupsandanarrayofstatisticsfiguresintheattributefigures.
Astatisticsgroupisdescribedby
Monitoring
363
group:Theidentifierofthegroup.name:Thenameofthegroup.description:Adescriptionofthegroup.
Astatisticsfigureisdescribedby
group:Theidentifierofthegrouptowhichthisfigurebelongs.identifier:Theidentifierofthefigure.Itisuniquewithinthegroup.name:Thenameofthefigure.description:Adescriptionofthefigure.type:Eithercurrent,accumulated,ordistribution.cuts:Thedistributionvector.units:Unitsinwhichthefigureismeasured.
Example:
shell>curl--dump-http://localhost:8529/_admin/statistics-description
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"groups":[
{
"group":"system",
"name":"ProcessStatistics",
"description":"StatisticsabouttheArangoDBprocess"
},
{
"group":"client",
"name":"ClientConnectionStatistics",
"description":"Statisticsabouttheconnections."
},
{
"group":"http",
"name":"HTTPRequestStatistics",
"description":"StatisticsabouttheHTTPrequests."
},
{
"group":"server",
"name":"ServerStatistics",
"description":"StatisticsabouttheArangoDBserver"
}
],
"figures":[
{
"group":"system",
"identifier":"userTime",
"name":"UserTime",
"description":"Amountoftimethatthisprocesshasbeenscheduledinusermode,measuredinseconds.",
"type":"accumulated",
"units":"seconds"
},
{
"group":"system",
"identifier":"systemTime",
"name":"SystemTime",
"description":"Amountoftimethatthisprocesshasbeenscheduledinkernelmode,measuredinseconds.",
"type":"accumulated",
"units":"seconds"
},
{
"group":"system",
"identifier":"numberOfThreads",
"name":"NumberofThreads",
"description":"Numberofthreadsinthearangodprocess.",
"type":"current",
"units":"number"
},
Monitoring
364
{
"group":"system",
"identifier":"residentSize",
"name":"ResidentSetSize",
"description":"Thetotalsizeofthenumberofpagestheprocesshasinrealmemory.Thisisjustthepageswhichcount
towardtext,data,orstackspace.Thisdoesnotincludepageswhichhavenotbeendemand-loadedin,orwhichareswappedout.
Theresidentsetsizeisreportedinbytes.",
"type":"current",
"units":"bytes"
},
{
"group":"system",
"identifier":"residentSizePercent",
"name":"ResidentSetSize",
"description":"Thepercentageofphysicalmemoryusedbytheprocessasresidentsetsize.",
"type":"current",
"units":"percent"
},
{
"group":"system",
"identifier":"virtualSize",
"name":"VirtualMemorySize",
"description":"OnWindows,thisfigurecontainsthetotalamountofmemorythatthememorymanagerhascommittedforth
earangodprocess.Onothersystems,thisfigurecontainsThesizeofthevirtualmemorytheprocessisusing.",
"type":"current",
"units":"bytes"
},
{
"group":"system",
"identifier":"minorPageFaults",
"name":"MinorPageFaults",
"description":"Thenumberofminorfaultstheprocesshasmadewhichhavenotrequiredloadingamemorypagefromdisk.
ThisfigureisnotreportedonWindows.",
"type":"accumulated",
"units":"number"
},
{
"group":"system",
"identifier":"majorPageFaults",
"name":"MajorPageFaults",
"description":"OnWindows,thisfigurecontainsthetotalnumberofpagefaults.Onothersystem,thisfigurecontains
thenumberofmajorfaultstheprocesshasmadewhichhaverequiredloadingamemorypagefromdisk.",
"type":"accumulated",
"units":"number"
},
{
"group":"client",
"identifier":"httpConnections",
"name":"ClientConnections",
"description":"Thenumberofconnectionsthatarecurrentlyopen.",
"type":"current",
"units":"number"
},
{
"group":"client",
"identifier":"totalTime",
"name":"TotalTime",
"description":"Totaltimeneededtoanswerarequest.",
"type":"distribution",
"cuts":[
0.01,
0.05,
0.1,
0.2,
0.5,
1
],
"units":"seconds"
},
{
"group":"client",
"identifier":"requestTime",
"name":"RequestTime",
"description":"Requesttimeneededtoanswerarequest.",
"type":"distribution",
"cuts":[
Monitoring
365
0.01,
0.05,
0.1,
0.2,
0.5,
1
],
"units":"seconds"
},
{
"group":"client",
"identifier":"queueTime",
"name":"QueueTime",
"description":"Queuetimeneededtoanswerarequest.",
"type":"distribution",
"cuts":[
0.01,
0.05,
0.1,
0.2,
0.5,
1
],
"units":"seconds"
},
{
"group":"client",
"identifier":"bytesSent",
"name":"BytesSent",
"description":"Bytessentsforarequest.",
"type":"distribution",
"cuts":[
250,
1000,
2000,
5000,
10000
],
"units":"bytes"
},
{
"group":"client",
"identifier":"bytesReceived",
"name":"BytesReceived",
"description":"Bytesreceivedsforarequest.",
"type":"distribution",
"cuts":[
250,
1000,
2000,
5000,
10000
],
"units":"bytes"
},
{
"group":"client",
"identifier":"connectionTime",
"name":"ConnectionTime",
"description":"Totalconnectiontimeofaclient.",
"type":"distribution",
"cuts":[
0.1,
1,
60
],
"units":"seconds"
},
{
"group":"http",
"identifier":"requestsTotal",
"name":"Totalrequests",
"description":"TotalnumberofHTTPrequests.",
"type":"accumulated",
"units":"number"
},
Monitoring
366
{
"group":"http",
"identifier":"requestsAsync",
"name":"Asyncrequests",
"description":"NumberofasynchronouslyexecutedHTTPrequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"http",
"identifier":"requestsGet",
"name":"HTTPGETrequests",
"description":"NumberofHTTPGETrequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"http",
"identifier":"requestsHead",
"name":"HTTPHEADrequests",
"description":"NumberofHTTPHEADrequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"http",
"identifier":"requestsPost",
"name":"HTTPPOSTrequests",
"description":"NumberofHTTPPOSTrequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"http",
"identifier":"requestsPut",
"name":"HTTPPUTrequests",
"description":"NumberofHTTPPUTrequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"http",
"identifier":"requestsPatch",
"name":"HTTPPATCHrequests",
"description":"NumberofHTTPPATCHrequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"http",
"identifier":"requestsDelete",
"name":"HTTPDELETErequests",
"description":"NumberofHTTPDELETErequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"http",
"identifier":"requestsOptions",
"name":"HTTPOPTIONSrequests",
"description":"NumberofHTTPOPTIONSrequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"http",
"identifier":"requestsOther",
"name":"otherHTTPrequests",
"description":"NumberofotherHTTPrequests.",
"type":"accumulated",
"units":"number"
},
{
"group":"server",
"identifier":"uptime",
"name":"ServerUptime",
Monitoring
367
"description":"Numberofsecondselapsedsinceserverstart.",
"type":"current",
"units":"seconds"
},
{
"group":"server",
"identifier":"physicalMemory",
"name":"PhysicalMemory",
"description":"Physicalmemoryinbytes.",
"type":"current",
"units":"bytes"
}
],
"error":false,
"code":200
}
ReturnCodes
200:Descriptionwasreturnedsuccessfully.
Examples
shell>curl--dump-http://localhost:8529/_admin/statistics-description
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Returnroleofaserverinacluster
GettoknowwhetherthisserverisaCoordinatororDB-Server
GET/_admin/server/role
Returnstheroleofaserverinacluster.Theroleisreturnedintheroleattributeoftheresult.Possiblereturnvaluesforroleare:
SINGLE:theserverisastandaloneserverwithoutclusteringCOORDINATOR:theserverisacoordinatorinaclusterPRIMARY:theserverisaprimarydatabaseserverinaclusterSECONDARY:theserverisasecondarydatabaseserverinaclusterAGENT:theserverisanagencynodeinaclusterUNDEFINED:inacluster,UNDEFINEDisreturnediftheserverrolecannotbedetermined.
ReturnCodes
200:Isreturnedinallcases.
Returnidofaserverinacluster
Gettoknowtheinternalidoftheserver
GET/_admin/server/id
Returnstheidofaserverinacluster.Theidisemptyifitisworkinginsingleservermode.
ReturnCodes
200:Isreturnedinallcases.
QueriesstatisticsofDBserver
allowstoquerythestatisticsofaDBserverinthecluster
Monitoring
368
GET/_admin/clusterStatistics
QueryParameters
DBserver(required):
ReturnCodes
200:isreturnedwheneverythingwentwell.400:theparameterDBserverwasnotgivenorisnottheIDofaDBserver403:serverisnotacoordinator.
Monitoring
369
HTTPInterfaceforEndpointsTheAPI/_api/endpointisdeprecated.Forclustermodethereis/_api/cluster/endpointstofindallcurrentcoordinatorendpoints(seebelow).
TheArangoDBservercanlistenforincomingrequestsonmultipleendpoints.
TheendpointsarenormallyspecifiedeitherinArangoDB'sconfigurationfileoronthecommand-line,usingthe"--server.endpoint"option.ThedefaultendpointforArangoDBistcp://127.0.0.1:8529ortcp://localhost:8529.
Pleasenotethatallendpointmanagementoperationscanonlybeaccessedviathedefaultdatabase(_system)andnoneoftheotherdatabases.
AskingaboutEndpointsviaHTTP
Getinformationaboutallcoordinatorendpoints
ThisAPIcallreturnsinformationaboutallcoordinatorendpoints(clusteronly).
GET/_api/cluster/endpoints
Returnsanobjectwithanattributeendpoints,whichcontainsanarrayofobjects,whicheachhavetheattributeendpoint,whosevalueisastringwiththeendpointdescription.Thereisanentryforeachcoordinatorinthecluster.Thismethodonlyworksoncoordinatorsinclustermode.Incaseofanerrortheerrorattributeissettotrue.
ReturnCodes
200:isreturnedwheneverythingwentwell.403:serverisnotacoordinatorormethodwasnotGET.
Returnlistofallendpoints
ThisAPIcallreturnsthelistofallendpoints(singleserver).
GET/_api/endpoint
THISAPIISDEPRECATED
Returnsanarrayofallconfiguredendpointstheserverislisteningon.
TheresultisaJSONarrayofJSONobjects,eachwith`"entrypoint"'astheonlyattribute,andwiththevaluebeingastringdescribingtheendpoint.
Note:retrievingthearrayofallendpointsisallowedinthesystemdatabaseonly.Callingthisactioninanyotherdatabasewillmaketheserverreturnanerror.
Example:
shell>curl--dump-http://localhost:8529/_api/endpoint
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"endpoint":"http://127.0.0.1:60154"
}
]
ReturnCodes
Endpoints
370
200:isreturnedwhenthearrayofendpointscanbedeterminedsuccessfully.400:isreturnediftheactionisnotcarriedoutinthesystemdatabase.405:TheserverwillrespondwithHTTP405ifanunsupportedHTTPmethodisused.
Examples
shell>curl--dump-http://localhost:8529/_api/endpoint
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"endpoint":"http://127.0.0.1:60154"
}
]
Endpoints
371
FoxxHTTPAPITheseroutesallowmanipulatingtheFoxxservicesinstalledinadatabase.
FormoreinformationonFoxxanditsJavaScriptAPIsseetheFoxxchapterofthemaindocumentation.
FoxxServices
372
FoxxServiceManagementThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingFoxxservices.
Listinstalledservices
listinstalledservices
GET/_api/foxx
Fetchesalistofservicesinstalledinthecurrentdatabase.
Returnsalistofobjectswiththefollowingattributes:
mount:themountpathoftheservicedevelopment:trueiftheserviceisrunningindevelopmentmodelegacy:trueiftheserviceisrunningin2.8legacycompatibilitymodeprovides:theservicemanifest'sprovidesvalueoranemptyobject
Additionallytheobjectmaycontainthefollowingattributesiftheyhavebeensetonthemanifest:
name:astringidentifyingtheservicetypeversion:asemver-compatibleversionstring
ReturnCodes
200:Returnediftherequestwassuccessful.
Servicedescription
servicemetadata
GET/_api/foxx/service
Fetchesdetailedinformationfortheserviceatthegivenmountpath.
Returnsanobjectwiththefollowingattributes:
mount:themountpathoftheservicepath:thelocalfilesystempathoftheservicedevelopment:trueiftheserviceisrunningindevelopmentmodelegacy:trueiftheserviceisrunningin2.8legacycompatibilitymodemanifest:thenormalizedJSONmanifestoftheservice
Additionallytheobjectmaycontainthefollowingattributesiftheyhavebeensetonthemanifest:
name:astringidentifyingtheservicetypeversion:asemver-compatibleversionstring
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassuccessful.400:Returnedifthemountpathisunknown.
Installnewservice
installnewservice
POST/_api/foxx
Installsthegivennewserviceatthegivenmountpath.
Management
373
Therequestbodycanbeanyofthefollowingformats:
application/zip:arawzipbundlecontainingaserviceapplication/javascript:astandaloneJavaScriptfileapplication/json:aservicedefinitionasJSONmultipart/form-data:aservicedefinitionasamultipartform
Aservicedefinitionisanobjectorformwiththefollowingpropertiesorfields:
configuration:aJSONobjectdescribingconfigurationvaluesdependencies:aJSONobjectdescribingdependencysettingssource:afullyqualifiedURLoranabsolutepathontheserver'sfilesystem
Whenusingmultipartdata,thesourcefieldcanalsoalternativelybeafilefieldcontainingeitherazipbundleorastandaloneJavaScriptfile.
WhenusingastandaloneJavaScriptfilethegivenfilewillbeexecutedtodefineourservice'sHTTPendpoints.Itisthesamewhichwouldbedefinedinthefieldmainoftheservicemanifest.
IfsourceisaURL,theURLmustbereachablefromtheserver.Ifsourceisafilesystempath,thepathwillberesolvedontheserver.IneithercasethepathorURLisexpectedtoresolvetoazipbundle.
Notethatwhenusingfilesystempathsinaclusterwithmultiplecoordinatorsthefilesystempathmustresolvetoequivalentfilesoneverycoordinator.
QueryParameters
mount(required):Mountpaththeserviceshouldbeinstalledat.development(optional):Settotruetoenabledevelopmentmode.setup(optional):Settofalsetonotruntheservice'ssetupscript.legacy(optional):Settotruetoinstalltheservicein2.8legacycompatibilitymode.
ReturnCodes
201:Returnediftherequestwassuccessful.
Uninstallservice
uninstallservice
DELETE/_api/foxx/service
Removestheserviceatthegivenmountpathfromthedatabaseandfilesystem.
Returnsanemptyresponseonsuccess.
QueryParameters
mount(required):Mountpathoftheinstalledservice.teardown(optional):Settofalsetonotruntheservice'steardownscript.
ReturnCodes
204:Returnediftherequestwassuccessful.
Replaceservice
replaceaservice
PUT/_api/foxx/service
Removestheserviceatthegivenmountpathfromthedatabaseandfilesystem.Theninstallsthegivennewserviceatthesamemountpath.
Thisisaslightlysaferequivalenttoperforminganuninstalloftheoldservicefollowedbyinstallingthenewservice.Thenewservice'smainandscriptfiles(ifany)willbecheckedforbasicsyntaxerrorsbeforetheoldserviceisremoved.
Therequestbodycanbeanyofthefollowingformats:
Management
374
application/zip:arawzipbundlecontainingaserviceapplication/javascript:astandaloneJavaScriptfileapplication/json:aservicedefinitionasJSONmultipart/form-data:aservicedefinitionasamultipartform
Aservicedefinitionisanobjectorformwiththefollowingpropertiesorfields:
configuration:aJSONobjectdescribingconfigurationvaluesdependencies:aJSONobjectdescribingdependencysettingssource:afullyqualifiedURLoranabsolutepathontheserver'sfilesystem
Whenusingmultipartdata,thesourcefieldcanalsoalternativelybeafilefieldcontainingeitherazipbundleorastandaloneJavaScriptfile.
WhenusingastandaloneJavaScriptfilethegivenfilewillbeexecutedtodefineourservice'sHTTPendpoints.Itisthesamewhichwouldbedefinedinthefieldmainoftheservicemanifest.
IfsourceisaURL,theURLmustbereachablefromtheserver.Ifsourceisafilesystempath,thepathwillberesolvedontheserver.IneithercasethepathorURLisexpectedtoresolvetoazipbundle.
Notethatwhenusingfilesystempathsinaclusterwithmultiplecoordinatorsthefilesystempathmustresolvetoequivalentfilesoneverycoordinator.
QueryParameters
mount(required):Mountpathoftheinstalledservice.teardown(optional):Settofalsetonotruntheoldservice'steardownscript.setup(optional):Settofalsetonotrunthenewservice'ssetupscript.legacy(optional):Settotruetoinstallthenewservicein2.8legacycompatibilitymode.
ReturnCodes
200:Returnediftherequestwassuccessful.
Upgradeservice
upgradeaservice
PATCH/_api/foxx/service
Installsthegivennewserviceontopoftheservicecurrentlyinstalledatthegivenmountpath.Thisisonlyrecommendedforswitchingbetweendifferentversionsofthesameservice.
Unlikereplacingaservice,upgradingaserviceretainstheoldservice'sconfigurationanddependencies(ifany)andshouldthereforeonlybeusedtomigrateanexistingservicetoanewerorequivalentservice.
Therequestbodycanbeanyofthefollowingformats:
application/zip:arawzipbundlecontainingaserviceapplication/javascript:astandaloneJavaScriptfileapplication/json:aservicedefinitionasJSONmultipart/form-data:aservicedefinitionasamultipartform
Aservicedefinitionisanobjectorformwiththefollowingpropertiesorfields:
configuration:aJSONobjectdescribingconfigurationvaluesdependencies:aJSONobjectdescribingdependencysettingssource:afullyqualifiedURLoranabsolutepathontheserver'sfilesystem
Whenusingmultipartdata,thesourcefieldcanalsoalternativelybeafilefieldcontainingeitherazipbundleorastandaloneJavaScriptfile.
WhenusingastandaloneJavaScriptfilethegivenfilewillbeexecutedtodefineourservice'sHTTPendpoints.Itisthesamewhichwouldbedefinedinthefieldmainoftheservicemanifest.
Management
375
IfsourceisaURL,theURLmustbereachablefromtheserver.Ifsourceisafilesystempath,thepathwillberesolvedontheserver.IneithercasethepathorURLisexpectedtoresolvetoazipbundle.
Notethatwhenusingfilesystempathsinaclusterwithmultiplecoordinatorsthefilesystempathmustresolvetoequivalentfilesoneverycoordinator.
QueryParameters
mount(required):Mountpathoftheinstalledservice.teardown(optional):Settotruetoruntheoldservice'steardownscript.setup(optional):Settofalsetonotrunthenewservice'ssetupscript.legacy(optional):Settotruetoinstallthenewservicein2.8legacycompatibilitymode.
ReturnCodes
200:Returnediftherequestwassuccessful.
Management
376
FoxxServiceconfiguration/dependenciesThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingFoxxservicesconfigurationanddependencies.
Getconfigurationoptions
getconfigurationoptions
GET/_api/foxx/configuration
Fetchesthecurrentconfigurationfortheserviceatthegivenmountpath.
Returnsanobjectmappingtheconfigurationoptionnamestotheirdefinitionsincludingahuman-friendlytitleandthecurrentvalue(ifany).
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassucessful.
Updateconfigurationoptions
updateconfigurationoptions
PATCH/_api/foxx/configuration
Replacesthegivenservice'sconfiguration.
Returnsanobjectmappingallconfigurationoptionnamestotheirnewvalues.
RequestBody(required)
AJSONobjectmappingconfigurationoptionnamestotheirnewvalues.Anyomittedoptionswillbeignored.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
Replaceconfigurationoptions
replaceconfigurationoptions
PUT/_api/foxx/configuration
Replacesthegivenservice'sconfigurationcompletely.
Returnsanobjectmappingallconfigurationoptionnamestotheirnewvalues.
RequestBody(required)
AJSONobjectmappingconfigurationoptionnamestotheirnewvalues.Anyomittedoptionswillberesettotheirdefaultvaluesormarkedasunconfigured.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
Getdependencyoptions
getdependencyoptions
GET/_api/foxx/dependencies
Fetchesthecurrentdependenciesforserviceatthegivenmountpath.
Configuration
377
Returnsanobjectmappingthedependencynamestotheirdefinitionsincludingahuman-friendlytitleandthecurrentmountpath(ifany).
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassucessful.
Updatedependenciesoptions
updatedependenciesoptions
PATCH/_api/foxx/dependencies
Replacesthegivenservice'sdependencies.
Returnsanobjectmappingalldependencynamestotheirnewmountpaths.
RequestBody(required)
AJSONobjectmappingdependencynamestotheirnewmountpaths.Anyomitteddependencieswillbeignored.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
Replacedependenciesoptions
replacedependenciesoptions
PUT/_api/foxx/dependencies
Replacesthegivenservice'sdependenciescompletely.
Returnsanobjectmappingalldependencynamestotheirnewmountpaths.
RequestBody(required)
AJSONobjectmappingdependencynamestotheirnewmountpaths.Anyomitteddependencieswillbedisabled.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
Configuration
378
FoxxServiceMiscellaneous
Listservicescripts
listservicescripts
GET/_api/foxx/scripts
Fetchesalistofthescriptsdefinedbytheservice.
Returnsanobjectmappingtherawscriptnamestohuman-friendlynames.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassucessful.
Runservicescript
runservicescript
POST/_api/foxx/scripts/{name}
Runsthegivenscriptfortheserviceatthegivenmountpath.
Returnstheexportsofthescript,ifany.
RequestBody(optional)
AnarbitraryJSONvaluethatwillbeparsedandpassedtothescriptasitsfirstargument.
PathParameters
name(required):Nameofthescripttorun.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassucessful.
Runservicetests
runservicetests
POST/_api/foxx/tests
Runsthetestsfortheserviceatthegivenmountpathandreturnstheresults.
Supportedtestreportersare:
default:asimplelistoftestcasessuite:anobjectoftestcasesnestedinsuitesstream:arawstreamoftestresultsxunit:anXUnit/JUnitcompatiblestructuretap:arawTAPcompatiblestream
TheAcceptrequestheadercanbeusedtofurthercontroltheresponseformat:
Whenusingthestreamreporterapplication/x-ldjsonwillresultintheresponsebodybeingformattedasanewline-delimitedJSONstream.
Whenusingthetapreportertext/plainortext/*willresultintheresponsebodybeingformattedasaplaintextTAPreport.
Miscellaneous
379
Whenusingthexunitreporterapplication/xmlortext/xmlwillresultintheresponsebodybeingformattedasXMLinsteadofJSONML.
Otherwisetheresponsebodywillbeformattedasnon-prettyprintedJSON.
QueryParameters
mount(required):Mountpathoftheinstalledservice.reporter(optional):Testreportertouse.idiomatic(optional):Usethematchingformatforthereporter,regardlessoftheAcceptheader.
ReturnCodes
200:Returnediftherequestwassucessful.
Enabledevelopmentmode
enabledevelopmentmode
POST/_api/foxx/development
Putstheserviceintodevelopmentmode.
Whiletheserviceisrunningindevelopmentmodetheservicewillbereloadedfromthefilesystemanditssetupscript(ifany)willbere-executedeverytimetheservicehandlesarequest.
WhenrunningArangoDBinaclusterwithmultiplecoordinatorsnotethatchangestothefilesystemononecoordinatorwillnotbereflectedacrosstheothercoordinators.Thismeansyoushouldtreatyourcoordinatorsasinconsistentaslongasanyserviceisrunningindevelopmentmode.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassucessful.
Disabledevelopmentmode
disabledevelopmentmode
DELETE/_api/foxx/development
Putstheserviceatthegivenmountpathintoproductionmode.
WhenrunningArangoDBinaclusterwithmultiplecoordinatorsthiswillreplacetheserviceonallothercoordinatorswiththeversiononthiscoordinator.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassucessful.
ServiceREADME
serviceREADME
GET/_api/foxx/readme
Fetchestheservice'sREADMEorREADME.mdfile'scontentsifany.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
Miscellaneous
380
200:Returnediftherequestwassucessful.204:ReturnedifnoREADMEfilewasfound.
Swaggerdescription
swaggerdescription
GET/_api/foxx/swagger
FetchestheSwaggerAPIdescriptionfortheserviceatthegivenmountpath.
TheresponsebodywillbeanOpenAPI2.0compatibleJSONdescriptionoftheserviceAPI.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassucessful.
Downloadservicebundle
downloadservicebundle
POST/_api/foxx/download
Downloadsazipbundleoftheservicedirectory.
Whendevelopmentmodeisenabled,thisalwayscreatesanewbundle.
OtherwisethebundlewillrepresenttheversionofaservicethatisinstalledonthatArangoDBinstance.
QueryParameters
mount(required):Mountpathoftheinstalledservice.
ReturnCodes
200:Returnediftherequestwassucessful.400:Returnedifthemountpathisunknown.
Commitlocalservicestate
commitlocalservicestate
POST/_api/foxx/commit
Commitsthelocalservicestateofthecoordinatortothedatabase.
Thiscanbeusedtoresolveserviceconflictsbetweencoordinatorsthatcannotbefixedautomaticallyduetomissingdata.
QueryParameters
replace(optional):Overwriteexistingservicefilesindatabaseeveniftheyalreadyexist.204:Returnediftherequestwassucessful.
Miscellaneous
381
HTTPInterfaceforUserManagementThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingusers.
Theinterfaceprovidesasimplemeanstoadd,update,andremoveusers.Allusersmanagedthroughthisinterfacewillbestoredinthesystemcollection_users.Youshouldnevermanipulatethe_userscollectiondirectly.
ThisspecializedinterfaceintentionallydoesnotprovideallfunctionalitythatisavailableintheregulardocumentRESTAPI.
PleasenotethatuseroperationsarenotincludedinArangoDB'sreplication.
CreateUser
Createanewuser.
POST/_api/user
AJSONobjectwiththesepropertiesisrequired:
passwd:Theuserpasswordasastring.Ifnopasswordisspecified,theemptystringwillbeused.IfyoupassthespecialvalueARANGODB_DEFAULT_ROOT_PASSWORD,thenthepasswordwillbesetthevaluestoredintheenvironmentvariableARANGODB_DEFAULT_ROOT_PASSWORD.ThiscanbeusedtopassaninstancevariableintoArangoDB.Forexample,theinstanceidentifierfromAmazon.active:Anoptionalflagthatspecifieswhethertheuserisactive.Ifnotspecified,thiswilldefaulttotrueuser:Thenameoftheuserasastring.Thisismandatory.extra:AnoptionalJSONobjectwitharbitraryextradataabouttheuser.
Createanewuser.YouneedserveraccesslevelAdministrateinordertoexecutethisRESTcall.
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/user<<EOF
{
"user":"admin@example",
"passwd":"secure"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"user":"admin@example",
"active":true,
"extra":{
},
"error":false,
"code":201
}
ReturnCodes
201:Returnediftheusercanbeaddedbytheserver400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.409:Returnedifauserwiththesamenamealreadyexists.
Examples
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/user<<EOF
UserManagement
382
{
"user":"admin@example",
"passwd":"secure"
}
EOF
HTTP/1.1201Created
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Setthedatabaseaccesslevel
Setthedatabaseaccesslevel.
PUT/_api/user/{user}/database/{dbname}
AJSONobjectwiththesepropertiesisrequired:
grant:Use"rw"tosetthedatabaseaccessleveltoAdministrate.Use"ro"tosetthedatabaseaccessleveltoAccess.Use"none"tosetthedatabaseaccessleveltoNoaccess.
Setsthedatabaseaccesslevelsforthedatabasedbnameofuseruser.YouneedtheAdministrateserveraccesslevelinordertoexecutethisRESTcall.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp/database/_system<<EOF
{
"grant":"rw"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"_system":"rw",
"error":false,
"code":200
}
PathParameters
user(required):Thenameoftheuser.dbname(required):Thenameofthedatabase.
ReturnCodes
200:Returnediftheaccesslevelwaschangedsuccessfully.400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.
Examples
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/user/admin@myapp/database/_system<<EOF
{
UserManagement
383
"grant":"rw"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Setthecollectionaccesslevel
Setthecollectionaccesslevel.
PUT/_api/user/{user}/database/{dbname}/{collection}
AJSONobjectwiththesepropertiesisrequired:
grant:Use"rw"tosetthecollectionlevelaccesstoRead/Write.Use"ro"tosetthecollectionlevelaccesstoReadOnly.Use"none"tosetthecollectionlevelaccesstoNoaccess.
Setsthecollectionaccesslevelforthecollectioninthedatabasedbnameforuseruser.YouneedtheAdministrateserveraccesslevelinordertoexecutethisRESTcall.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp/database/_system/reports<<EOF
{
"grant":"rw"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"_system/reports":"rw",
"error":false,
"code":200
}
PathParameters
user(required):Thenameoftheuser.dbname(required):Thenameofthedatabase.collection(required):Thenameofthecollection.
ReturnCodes
200:Returnediftheaccesspermissionswerechangedsuccessfully.400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.
Examples
shell>curl-XPUT--data-binary@---dump-
http://localhost:8529/_api/user/admin@myapp/database/_system/reports<<EOF
{
"grant":"rw"
UserManagement
384
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Clearthedatabaseaccesslevel
Clearthedatabaseaccesslevel,revertbacktothedefaultaccesslevel
DELETE/_api/user/{user}/database/{dbname}
PathParameters
user(required):Thenameoftheuser.dbname(required):Thenameofthedatabase.
Clearsthedatabaseaccesslevelforthedatabasedbnameofuseruser.Asconsequencethedefaultdatabaseaccesslevelisused.Ifthereisnodefineddefaultdatabaseaccesslevel,itdefaultstoNoaccess.Youneedpermissiontothe_systemdatabaseinordertoexecutethisRESTcall.
Notethatfortechnicalreasonsthiscurrentlyonlyworksinsingleservermode.Forclusters,usethePUTverbandanexplicitsettingfornow.
Example:
shell>curl-XDELETE--dump-http://localhost:8529/_api/user/admin@myapp/database/_system
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
"{\"error\":false,\"code\":202}"
ReturnCodes
202:Returnediftheaccesspermissionswerechangedsuccessfully.400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest.
Examples
shell>curl-XDELETE--dump-
http://localhost:8529/_api/user/admin@myapp/database/_system
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
"{\"error\":false,\"code\":202}"
Clearthecollectionaccesslevel
Clearthecollectionaccesslevel,revertbacktothedefaultaccesslevel
DELETE/_api/user/{user}/database/{dbname}/{collection}
UserManagement
385
PathParameters
user(required):Thenameoftheuser.dbname(required):Thenameofthedatabase.collection(required):Thenameofthecollection.
Clearsthecollectionaccesslevelforthecollectioncollectioninthedatabasedbnameofuseruser.Asconsequencethedefaultcollectionaccesslevelisused.Ifthereisnodefineddefaultcollectionaccesslevel,itdefaultstoNoaccess.Youneedpermissionstothe_systemdatabaseinordertoexecutethisRESTcall.
Notethatfortechnicalreasonsthiscurrentlyonlyworksinsingleservermode.Forclusters,usethePUTverbandanexplicitsettingfornow.
Example:
shell>curl-XDELETE--dump-http://localhost:8529/_api/user/admin@myapp/database/_system/reports
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
"{\"error\":false,\"code\":202}"
ReturnCodes
202:Returnediftheaccesspermissionswerechangedsuccessfully.400:Iftherewasanerror
Examples
shell>curl-XDELETE--dump-
http://localhost:8529/_api/user/admin@myapp/database/_system/reports
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
"{\"error\":false,\"code\":202}"
Listtheaccessibledatabasesforauser
Listtheaccessibledatabasesforauser
GET/_api/user/{user}/database/
PathParameters
user(required):Thenameoftheuserforwhichyouwanttoquerythedatabases.
QueryParameters
full(optional):Returnthefullsetofaccesslevelsforalldatabasesandallcollections.
Fetchthelistofdatabasesavailabletothespecifieduser.YouneedAdministratefortheserveraccesslevelinordertoexecutethisRESTcall.
ThecallwillreturnaJSONobjectwiththeper-databaseaccessprivilegesforthespecifieduser.Theresultobjectwillcontainthedatabasesnamesasobjectkeys,andtheassociatedprivilegesforthedatabaseasvalues.
Incaseyouspecifiedfull,theresultwillcontainthepermissionsforthedatabasesaswellasthepermissionsforthecollections.
UserManagement
386
Example:
shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":{
"_system":"rw"
}
}
Example:Withthefullresponseformat:
shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database?full=true
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":{
"_system":{
"permission":"rw",
"collections":{
"_statisticsRaw":"undefined",
"_modules":"undefined",
"_queues":"undefined",
"_aqlfunctions":"undefined",
"_appbundles":"undefined",
"_graphs":"undefined",
"_routing":"undefined",
"_jobs":"undefined",
"animals":"undefined",
"_frontend":"undefined",
"_users":"undefined",
"_statistics":"undefined",
"_statistics15":"undefined",
"_apps":"undefined",
"demo":"undefined",
"*":"none"
}
},
"*":{
"permission":"none"
}
}
}
ReturnCodes
200:Returnedifthelistofavailabledatabasescanbereturned.400:Iftheaccessprivilegesarenotrightetc.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.
Examples
shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/
UserManagement
387
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyWiththefullresponseformat:
shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database?
full=true
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Getthedatabaseaccesslevel
Getspecificdatabaseaccesslevel
GET/_api/user/{user}/database/{database}
PathParameters
user(required):Thenameoftheuserforwhichyouwanttoquerythedatabases.database(required):Thenameofthedatabasetoquery
Fetchthedatabaseaccesslevelforaspecificdatabase
Example:
shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":"rw"
}
ReturnCodes
200:Returnediftheacccesslevelcanbereturned400:Iftheaccessprivilegesarenotrightetc.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.
Examples
shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
UserManagement
388
showresponsebody
Getthespecificcollectionaccesslevel
Getthecollectionaccesslevel
GET/_api/user/{user}/database/{database}/{collection}
PathParameters
user(required):Thenameoftheuserforwhichyouwanttoquerythedatabases.database(required):Thenameofthedatabasetoquerycollection(required):Thenameofthecollection
Returnsthecollectionaccesslevelforaspecificcollection
Example:
shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":"none"
}
ReturnCodes
200:Returnediftheacccesslevelcanbereturned400:Iftheaccessprivilegesarenotrightetc.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.
Examples
shell>curl--dump-
http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
ReplaceUser
Replaceanexistinguser.
PUT/_api/user/{user}
PathParameters
user(required):Thenameoftheuser
AJSONobjectwiththesepropertiesisrequired:
UserManagement
389
passwd:Theuserpasswordasastring.Specifyingapasswordismandatory,buttheemptystringisallowedforpasswordsactive:Anoptionalflagthatspecifieswhethertheuserisactive.Ifnotspecified,thiswilldefaulttotrueextra:AnoptionalJSONobjectwitharbitraryextradataabouttheuser.
Replacesthedataofanexistinguser.Thenameofanexistingusermustbespecifiedinuser.YouneedserveraccesslevelAdministrateinordertoexecutethisRESTcall.Additionally,ausercanchangehis/herowndata.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp<<EOF
{
"passwd":"secure"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"user":"admin@myapp",
"active":true,
"extra":{
},
"error":false,
"code":200
}
ReturnCodes
200:Isreturnediftheuserdatacanbereplacedbytheserver.400:TheJSONrepresentationismalformedormandatorydataismissingfromtherequest401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.404:Thespecifieduserdoesnotexist
Examples
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp
<<EOF
{
"passwd":"secure"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
ModifyUser
Modifyattributesofanexistinguser
PATCH/_api/user/{user}
PathParameters
user(required):Thenameoftheuser
UserManagement
390
AJSONobjectwiththesepropertiesisrequired:
passwd:Theuserpasswordasastring.Specifyingapasswordismandatory,buttheemptystringisallowedforpasswordsactive:Anoptionalflagthatspecifieswhethertheuserisactive.Ifnotspecified,thiswilldefaulttotrueextra:AnoptionalJSONobjectwitharbitraryextradataabouttheuser.
Partiallyupdatesthedataofanexistinguser.Thenameofanexistingusermustbespecifiedinuser.YouneedserveraccesslevelAdministrateinordertoexecutethisRESTcall.Additionally,ausercanchangehis/herowndata.
Example:
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp<<EOF
{
"passwd":"secure"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"user":"admin@myapp",
"active":true,
"extra":{
},
"error":false,
"code":200
}
ReturnCodes
200:Isreturnediftheuserdatacanbereplacedbytheserver.400:TheJSONrepresentationismalformedormandatorydataismissingfromtherequest.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.404:Thespecifieduserdoesnotexist
Examples
shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp
<<EOF
{
"passwd":"secure"
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
RemoveUser
deleteauserpermanently.
DELETE/_api/user/{user}
PathParameters
UserManagement
391
user(required):Thenameoftheuser
Removesanexistinguser,identifiedbyuser.YouneedAdministratefortheserveraccesslevelinordertoexecutethisRESTcall.
Example:
shell>curl-XDELETE--data-binary@---dump-http://localhost:8529/_api/user/userToDelete@myapp<<EOF
{
}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":202
}
ReturnCodes
202:Isreturnediftheuserwasremovedbytheserver401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.404:Thespecifieduserdoesnotexist
Examples
shell>curl-XDELETE--data-binary@---dump-
http://localhost:8529/_api/user/userToDelete@myapp<<EOF
{
}
EOF
HTTP/1.1202Accepted
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":202
}
FetchUser
fetchthepropertiesofauser.
GET/_api/user/{user}
PathParameters
user(required):Thenameoftheuser
Fetchesdataaboutthespecifieduser.YoucanfetchinformationaboutyourselforyouneedtheAdministrateserveraccesslevelinordertoexecutethisRESTcall.
Example:
shell>curl--dump-http://localhost:8529/_api/user/admin@myapp
UserManagement
392
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"user":"admin@myapp",
"active":true,
"extra":{
},
"error":false,
"code":200
}
ReturnCodes
200:Theuserwasfound.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.404:Theuserwiththespecifiednamedoesnotexist.
Examples
shell>curl--dump-http://localhost:8529/_api/user/admin@myapp
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
ListavailableUsers
fetchthepropertiesofauser.
GET/_api/user/
Fetchesdataaboutallusers.YouneedtheAdministrateserveraccesslevelinordertoexecutethisRESTcall.Otherwise,youwillonlygetinformationaboutyourself.
ThecallwillreturnaJSONobjectwithatleastthefollowingattributesonsuccess:
user:Thenameoftheuserasastring.active:Anoptionalflagthatspecifieswhethertheuserisactive.extra:AnoptionalJSONobjectwitharbitraryextradataabouttheuser.
Example:
shell>curl--dump-http://localhost:8529/_api/user
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200,
"result":[
{
"user":"admin",
"active":true,
"extra":{
}
},
UserManagement
393
{
"user":"root",
"active":true,
"extra":{
}
},
{
"user":"tester",
"active":false,
"extra":{
}
}
]
}
ReturnCodes
200:Theusersthatwerefound.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.
Examples
shell>curl--dump-http://localhost:8529/_api/user
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
UserManagement
394
HTTPtasksInterfaceFollowingyouhaveArangoDB'sHTTPInterfaceforTasks.
TherearealsosomeexamplesprovidedforeveryAPIaction.
Fetchalltasksoronetask
Retrievesallcurrentlyactiveservertasks
GET/_api/tasks/
fetchesallexistingtasksontheserver
Example:Fetchingalltasks
shell>curl--dump-http://localhost:8529/_api/tasks
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"id":"statistics-gc",
"name":"statistics-gc",
"created":1516907609.406109,
"type":"periodic",
"period":450,
"offset":406.020662,
"command":"(function(params){require('@arangodb/statistics').garbageCollector();})(params);",
"database":"_system"
},
{
"id":"statistics-average-collector",
"name":"statistics-average-collector",
"created":1516907609.4059584,
"type":"periodic",
"period":900,
"offset":20,
"command":"(function(params){require('@arangodb/statistics').historianAverage();})(params);",
"database":"_system"
},
{
"id":"statistics-collector",
"name":"statistics-collector",
"created":1516907609.4056144,
"type":"periodic",
"period":10,
"offset":1,
"command":"(function(params){require('@arangodb/statistics').historian();})(params);",
"database":"_system"
},
{
"id":"84",
"name":"user-definedtask",
"created":1516907599.4534233,
"type":"periodic",
"period":1,
"offset":0.000001,
"command":"(function(params){(function(){
require('@arangodb/foxx/queues/manager').manage();
})(params)})(params);",
"database":"_system"
}
]
Tasks
395
200:Thelistoftasks
Examples
Fetchingalltasks
shell>curl--dump-http://localhost:8529/_api/tasks
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
[
{
"id":"statistics-gc",
"name":"statistics-gc",
"created":1516907609.406109,
"type":"periodic",
"period":450,
"offset":406.020662,
"command":"(function(params){require('@arangodb/statistics').garbageCollector();
})(params);",
"database":"_system"
},
{
"id":"statistics-average-collector",
"name":"statistics-average-collector",
"created":1516907609.4059584,
"type":"periodic",
"period":900,
"offset":20,
"command":"(function(params){require('@arangodb/statistics').historianAverage();
})(params);",
"database":"_system"
},
{
"id":"statistics-collector",
"name":"statistics-collector",
"created":1516907609.4056144,
"type":"periodic",
"period":10,
"offset":1,
"command":"(function(params){require('@arangodb/statistics').historian();})
(params);",
"database":"_system"
},
{
"id":"84",
"name":"user-definedtask",
"created":1516907599.4534233,
"type":"periodic",
"period":1,
"offset":0.000001,
"command":"(function(params){(function(){\n
require('@arangodb/foxx/queues/manager').manage();\n})(params)})(params);",
"database":"_system"
Tasks
396
}
]
Fetchonetaskwithid
Retrievesonecurrentlyactiveservertask
GET/_api/tasks/{id}
id(required):Theidofthetasktofetch.
fetchesoneexistingtasksontheserverspecifiedbyid
Example:Fetchingasingletaskbyitsid
shell>curl--dump-http://localhost:8529/_api/tasks/statistics-average-collector
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"id":"statistics-average-collector",
"name":"statistics-average-collector",
"created":1516907609.4059584,
"type":"periodic",
"period":900,
"offset":20,
"command":"(function(params){require('@arangodb/statistics').historianAverage();})(params);",
"database":"_system",
"error":false,
"code":200
}
Example:tryingtofetchanon-existingtask
shell>curl--dump-http://localhost:8529/_api/tasks/non-existing-task
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"code":404,
"errorNum":1852,
"errorMessage":"tasknotfound"
}
200:Therequestedtask
Examples
Fetchingasingletaskbyitsid
shell>curl--dump-http://localhost:8529/_api/tasks/statistics-average-collector
HTTP/1.1200OK
content-type:application/json;charset=utf-8
Tasks
397
x-content-type-options:nosniff
showresponsebodytryingtofetchanon-existingtask
shell>curl--dump-http://localhost:8529/_api/tasks/non-existing-task
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
createsatask
createsanewtask
POST/_api/tasks
AJSONobjectwiththesepropertiesisrequired:
params:Theparameterstobepassedintocommandoffset:Numberofsecondsinitialdelaycommand:TheJavaScriptcodetobeexecutedname:Thenameofthetaskperiod:numberofsecondsbetweentheexecutions
createsanewtaskwithageneratedid
Example:
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/tasks/<<EOF
{
"name":"SampleTask",
"command":"(function(params){require('@arangodb').print(params);})(params)",
"params":{
"foo":"bar",
"bar":"foo"
},
"period":2
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"id":"12983",
"name":"SampleTask",
"created":1516907628.2369483,
"type":"periodic",
"period":2,
"offset":0,
"command":"(function(params){(function(params){require('@arangodb').print(params);})(params)})(params);",
"database":"_system",
"error":false,
"code":200
}
shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/12983
Tasks
398
ReturnCodes
400:Ifthepostbodyisnotaccurate,aHTTP400isreturned.
Examples
shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/tasks/<<EOF
{
"name":"SampleTask",
"command":"(function(params){require('@arangodb').print(params);})(params)",
"params":{
"foo":"bar",
"bar":"foo"
},
"period":2
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
createsataskwithid
registersanewtaskwithapre-definedid
PUT/_api/tasks/{id}
id(required):Theidofthetasktocreate
AJSONobjectwiththesepropertiesisrequired:
params:Theparameterstobepassedintocommandoffset:Numberofsecondsinitialdelaycommand:TheJavaScriptcodetobeexecutedname:Thenameofthetaskperiod:numberofsecondsbetweentheexecutions
registersanewtaskwiththespecifiedid
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/tasks/sampleTask<<EOF
{
"id":"SampleTask",
"name":"SampleTask",
"command":"(function(params){require('@arangodb').print(params);})(params)",
"params":{
"foo":"bar",
"bar":"foo"
},
"period":2
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
Tasks
399
"id":"sampleTask",
"name":"SampleTask",
"created":1516907628.2489061,
"type":"periodic",
"period":2,
"offset":0,
"command":"(function(params){(function(params){require('@arangodb').print(params);})(params)})(params);",
"database":"_system",
"error":false,
"code":200
}
ReturnCodes
400:Ifthetaskidalreadyexistsortherestbodyisnotaccurate,HTTP400isreturned.
Examples
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/tasks/sampleTask
<<EOF
{
"id":"SampleTask",
"name":"SampleTask",
"command":"(function(params){require('@arangodb').print(params);})(params)",
"params":{
"foo":"bar",
"bar":"foo"
},
"period":2
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
deletesthetaskwithid
deletesonecurrentlyactiveservertask
DELETE/_api/tasks/{id}
id(required):Theidofthetasktodelete.
Deletesthetaskidentifiedbyidontheserver.
Example:tryingtodeletenonexistingtask
shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/NoTaskWithThatName
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":true,
"code":404,
"errorNum":1852,
Tasks
400
"errorMessage":"tasknotfound"
}
Example:RemoveexistingTask
shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/SampleTask
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200
}
ReturnCodes
404:Ifthetaskidisunknown,thenanHTTP404isreturned.
Examples
tryingtodeletenonexistingtask
shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/NoTaskWithThatName
HTTP/1.1404NotFound
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyRemoveexistingTask
shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/SampleTask
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"error":false,
"code":200
}
Tasks
401
HTTPInterfaceforAgencyfeature
Configuration
Atalltimes,i.e.regardlessofthestateoftheagentsandthecurrenthealthoftheRAFTconsensus,onecaninvoketheconfigurationAPI:
curlhttp://$SERVER:$PORT/_api/agency/config
Here,andinallsubsequentcalls,weassumethat$SERVERisreplacedbytheservernameand$PORTisreplacedbytheportnumber.Weusecurlthroughoutfortheexamples,butanyclientlibraryperformingHTTPrequestsshoulddo.Theoutputmightlooksomewhatlikethis
{
"term":1,
"leaderId":"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98",
"lastCommitted":1,
"lastAcked":{
"ac129027-b440-4c4f-84e9-75c042942171":0.21,
"c54dbb8a-723d-4c82-98de-8c841a14a112":0.21,
"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98":0
},
"configuration":{
"pool":{
"ac129027-b440-4c4f-84e9-75c042942171":"tcp://localhost:8531",
"c54dbb8a-723d-4c82-98de-8c841a14a112":"tcp://localhost:8530",
"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98":"tcp://localhost:8529"
},
"active":[
"ac129027-b440-4c4f-84e9-75c042942171",
"c54dbb8a-723d-4c82-98de-8c841a14a112",
"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98"
],
"id":"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98",
"agencysize":3,
"poolsize":3,
"endpoint":"tcp://localhost:8529",
"minping":0.5,
"maxping":2.5,
"supervision":false,
"supervisionfrequency":5,
"compactionstepsize":1000,
"supervisiongraceperiod":120
}
}
Thisistheactualoutputofahealthyagency.Theconfigurationoftheagencyisfoundintheconfigurationsectionasyoumighthaveguessed.Itispopulatedbystaticinformationonthestartupparameterslikeagencysize,theoncegenerateduniqueidetc.ItholdsinformationontheinvariantsoftheRAFTalgorithmanddatacompaction.
TheremainingdatareflectthevariantentitiesinRAFT,astermandleaderId,alsosomedebuginformationonhowlongthelastleadershipvotewasreceivedfromanyparticularagencymember.Lowtermnumbersonahealthynetworkareanindicationofgoodoperationenvironemnt,whileoftenincreasingtermnumbersindicate,thatthenetworkenvironemntandstabilitysuggesttoraisetheRAFTparametersminpingand'maxping'accordingly.
Key-ValuestoreAPIs
Generally,alldocumentIOtoandfromthekey-valuestoreconsistsofJSONarrays.TheouterArrayisanenvelopeformultiplereadorwritetransactions.Theresultsarearraysareanenvelopearoundtheresultscorrespondingtotheorderoftheincomingtransactions.
Considerthefollowingwriteoperationintoaprestineagency:
curl-Lhttp://$SERVER:$PORT/_api/agency/write-d'[[{"a":{"op":"set","new":{"b":{"c":[1,2,3]},"e":12}},"d":{"op":"set","new":f
alse}}]]'
Agency
402
[{results:[1]}]
Andthesubsequentreadoperation
curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/"]]'
[
{
"a":{
"b":{
"c":[1,2,3]
},
"e":12
},
"d":false
}
]
InthefirststepwecommitedasingletransactionthatcommitstheJSONdocumentinsidetheinnertransactionarraytotheagency.Theresultis[1],whichisthereplicatedlogindex.Repeatedinvocationwillyieldgrowinglognumbers2,3,4,etc.
Thereadaccessisacompleteaccesstothekey-valuestoreindicatedbyaccesstoit'srootelementandreturnstheresultasanarraycorrespondingtotheoutermostarrayinthereadtransaction.
Let'sdiginsomedeeper.
ReadAPI
Let'sstartwiththeaboveinitialisedkey-valuestoreinthefollowing.Letusvisitthefollowingreadoperations:
curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b"]]'
[
{
"a":{
"b":{
"c":[1,2,3]
}
}
}
]
And
curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/c"]]'
[
{
"a":{
"b":{
"c":[1,2,3]
}
}
}
]
Notethattheaboveresultsareidentical,meaningthatresultsobtainedfromtheagencyarealwaysreturnwithfullpath.
Thesecondouterarraybracketsinreadoperationscorrespondtotransactions,meaningthattheresultisguaranteedtohavebeenacquiredwithoutawritetransactioninbetween:
curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/e"],["/d","/a/b"]]'
Agency
403
[
{
"a":{
"e":12
}
},
{
"a":{
"b":{
"c":[1,2,3
]
}
},
"d":false
}
]
Whilethefirsttransactionconsistsofasinglereadaccesstothekey-value-storethusstrechtingthemeaningofthewordtransaction,thesecondbracketactuallyholdtwodisjunctreadaccesses,whichhavebeenjoinedwithinzero-time,i.e.withoutawriteaccessinbetween.Thatistosaythat"/d"cannothavechangedbefore"/a/b"hadbeenacquired.
Let'strytofetchavaluefromthekey-value-store,whichdoesnotexist:
curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/d"]]'
[
{
"a":{
"b":{}
}
}
]
Theresultreturnsthecrosssectionoftherequestedpathandthekey-value-storecontents."/a/b"exists,butthereisnokey"/a/b/d".Thusthefollowingtransactionwillyield:
curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/d","/d"]]'
[
{
"a":{
"b":{}
},
"d":false
}
]
Andthislastreadoperationshouldreturn:
curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/c"],["/a/b/d"],["/a/x/y"],["/y"],["/a/b","/a/x"]]'
[
{"a":{"b":{"c":[1,2,3]}}},
{"a":{"b":{}}},
{"a":{}},
{},
{"a":{"b":{"c":[1,2,3]}}}
]
WriteAPI
Agency
404
ThewriteAPImustobviouslybemoreversatileandneedsamoredetailedappreciation.Writeoperationsarearraysoftransactionswithpreconditions,i.e.[[U,P]],wherethesystemtriestoapplyallupdatesintheouterarrayinturn,rejectingthosewhosepreconditionisnotfulfilledbythecurrentstate.Itisguaranteedthatthetransactionsinthewriterequestaresequencedadjacenttoeachother(withnointerventionfromotherwriterequests).Onlytheoneswithfailedpreconditionsareleftout.
ForP,thevalueofakeyisanobjectwithattributes"old","oldNot","oldEmpty"or"isArray".With"old"onecanspecifyaJSONvaluethathastobepresentfortheconditiontobefulfilled.With"oldNot"onemaycheckforavaluetonotbeequaltothetest.Whilewith"oldEmpty",whichcantakeabooleanvalue,onecanspecifythatthekeyvalueneedstobenotsettrueorsettoanarbitraryvaluefalse.With"isArray"onecanspecifythatthevaluemustbeanarray.Asashortcut,"old"valuesofscalarorarraytypemaybestoreddirectlyintheattribute.Examples:
{"/a/b/c":{"old":[1,2,3]}}
isapreconditionspecifyingthatthepreviousvalueofthekey"/a/b/c"keymustbe[1,2,3].Ifandonlyifthevalueofthepreconditionisnotanobjectweprovideanotation,wherethekeyworkoldmaybeomitted.Thus,theabovecheckmaybeshortcutas
{"/a/b/c":[1,2,3]}
Considertheagencyininitialisedasabovelet'sreviewtheresponsesfromtheagencyasfollows:
curl-Lhttp://$SERVER:$PORT/_api/agency/write-d'[[{"/a/b/c":{"op":"set","new":[1,2,3,4]},"/a/b/pi":{"op":"set","new":"somet
ext"}},{"/a/b/c":{"old":[1,2,3]}}]]'
{
"results":[19]
}
Theconditionisfulfilledinthefirstrunandwouldbewronginasecondreturning
{
"results":[0]
}
0asaresultmeansthatthepreconditionfailedandno"real"lognumberwasreturned.
{"/a/e":{"oldEmpty":false}}
meansthatthevalueofthekey"a/e"mustbeset(tosomething,whichcanbenull!).Thecondition
{"/a/e":{"oldEmpty":true}}
meansthatthevalueofthekey"a/e"mustbeunset.Thecondition
{"/a/b/c":{"isArray":true}}
meansthatthevalueofthekey"a/b/c"mustbeanarray.
TheupdatevalueUisanobject,theattributenamesareagainkeystringsandthevaluesareobjectswithoptionalattributes"new","op"and"ttl".Theyhavethefollowingmeaning:
"op"determinestheoperation,possiblevaluesare"set"(thedefault,ifleftout),"delete","increment","decrement","push","pop","shift"or"prepend"
"new"isthenewvalue,canbeomittedforthe"delete"operationandfor"increment"and"decrement",where1isimplied
"ttl",ifpresent,thenewvaluethatisbeingsetgetsatimetoliveinseconds,givenbyanumericvalueinthisattribute.Itisonlyguaranteedthattheactualremovalofthevalueisdoneaccordingtothesystemclock,souptoclockskewbetweenservers.Theremovalisdonebyanadditionalwritetransactionthatisautomaticallygeneratedbetweentheregularwrites.
Agency
405
Additionalrule:Ifnoneof"new"and"op"issetorthevalueisnotevenanobject,thenthisistobeinterpretedasifitwere
{"op":"set","new":<VALUE>}
whichamountstosettingthevaluewithnoprecondition.
Examples:
{"/a":{"op":"set","new":12}}
setsthevalueofthekey"/a"to12.Thesamecouldhavebeenachievedby
{"/a":12}
orby
{"/a":{"new":12}}
Theoperation
{"/a/b":{"new":{"c":[1,2,3,4]}}}
setsthekey"/a/b"to{"c":[1,2,3,4]}.Notethatintheaboveexamplethisisthesameassettingthevalueof"/a/b/c"to[1,2,3,4].Thedifferenceis,thatifa/bhadothersubattributes,thenthistransactionwoulddeletealltheseotherattributesandmake"/a/b"equalto{"c":[1,2,3,4]},whereassetting"/a/b/c"to[1,2,3,4]wouldretainallattributesotherthan"c"in"/a/b".
Herearesomemoreexamplesforfulltransactions(update/preconditionpairs).Thetransaction
[{"/a/b":{"new":{"c":[1,2,3,4]}}},
{"/a/b":{"old":{"c":[1,2,3]}}}]
setsthekey"/a/b"to{"c":[1,2,3,4]}ifandonlyifitwas{"c":[1,2,3]}before.Notethatthisfailsif"/a/b"hadotherattributesthan"c".Thetransaction
[{"/x":{"op":"delete"}},
{"/x":{"old":false}}]
clearsthevalueofthekey"/x"ifthisoldvaluewasfalse.
[{"/y":{"new":13},
{"/y":{"oldEmpty":true}}}
setsthevalueof"/y"to13,butonly,ifitwasunsetbefore.
[{"/z":{"op":"push","new":"Max"}}]
appendsthestring"Max"totheendoftheliststoredinthe"z"attribute,orcreatesanarray["Max"]in"z"ifitwasunsetornotanarray.
[{"/u":{"op":"pop"}}]
removesthelastentryofthearraystoredunder"u",ifthevalueof"u"isnotsetornotanarray.
HTTP-headersforwriteoperations
X-ArangoDB-Agency-Modewithpossiblevalues"waitForCommitted","waitForSequenced"and"noWait".
Agency
406
Inthefirstcasethewriteoperationonlyreturnswhenthecommittothereplicatedloghasactuallyhappened.Inthesecondcasethewriteoperationreturnswhenthewritetransactionsthatfulfilledtheirpreconditionshavebeensequencedandthusitisknown,whichofthewritetransactionsinthegivenarrayhadfulfilledpreconditions.InbothcasesthebodyisaJSONarraycontainingtheindexesofthetransactionsinthelistthathadfulfilledpreconditions.
Inthelastcase,"noWait",theoperationreturnsimmediately,anemptybodyisreturned.Togetanyinformationabouttheresultoftheoperationonehastospecifyatag(seebelow)andaskaboutthestatuslateron.
X-ArangoDB-Agency-TagwithanarbitraryUTF-8stringvalue.
Observers
Externalservicestotheagencymayannouncethemselvesorotherstobeobserversofarbitraryexistingorfuturekeysinthekey-value-store.Theagencymusttheninformtheobservingserviceofanychangestothesubtreebelowtheobservedkey.ThenotificationisdonebyvirtueofPOSTrequeststoarequiredvalidURL.
Inordertoobserveanyfuturemodificationbelowsay"/a/b/c",aobserverisannouncedthroughpostingthebelowdocumenttotheagency’swriteRESThandler:
[{"/a/b/c":
{"op":"observe",
"url":"http://<host>:<port>/<path>"
}
}]
Theobserverisnotifiedofanychangestothattargetuntilsuchtimethatitremovesitselfasanobserverofthatkeythrough
[{"/a/b/c":
{"op":"unobserve",
"url":“http://<host>:<port>/<path>"}}]
Notethatthelastdocumentremovesallobservationsfromentitiesbelow"/a/b/c".Inparticular,issuing
[{"/":"unobserve","url":"http://<host>:<port>/<path>"}]
willresultintheremovalofallobservationsforURL"http://<host>:<port>/<path>".ThenotifyingPOSTrequestsaresubmittedimmediatelywithanycompletearrayofchangestothereaddboftheleaderofcreate,modifyanddeleteeventsaccordingly;Thebody
{"term":"5",
"index":167,
"/":{
"/a/b/c":{"op":"modify","old":1,"new":2}},
"/constants/euler":{"op":"create","new":2.718281828459046},
"/constants/pi":{"op":"delete"}}}
Agency
407
HTTPInterfaceforMiscellaneousfunctionsThisisanoverviewofArangoDB'sHTTPinterfaceformiscellaneousfunctions.
Returnserverversion
returnstheserverversionnumber
GET/_api/version
QueryParameters
details(optional):Ifsettotrue,theresponsewillcontainadetailsattributewithadditionalinformationaboutincludedcomponentsandtheirversions.TheattributenamesandinternalsofthedetailsobjectmayvarydependingonplatformandArangoDBversion.
Returnstheservernameandversionnumber.TheresponseisaJSONobjectwiththefollowingattributes:
AjsondocumentwiththesePropertiesisreturned:
HTTP200
isreturnedinallcases.
version:theserverversionstring.Thestringhastheformat"major.minor.sub".majorandminorwillbenumeric,andsubmaycontainanumberoratextualversion.details:anoptionalJSONobjectwithadditionaldetails.Thisisreturnedonlyifthedetailsqueryparameterissettotrueintherequest.server:willalwayscontainarango
Example:Returntheversioninformation
shell>curl--dump-http://localhost:8529/_api/version
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"server":"arango",
"version":"3.3.3",
"license":"community"
}
Example:Returntheversioninformationwithdetails
shell>curl--dump-http://localhost:8529/_api/version?details=true
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"server":"arango",
"version":"3.3.3",
"license":"community",
"details":{
Miscellaneousfunctions
408
"architecture":"64bit",
"arm":"false",
"asan":"false",
"asm-crc32":"true",
"assertions":"true",
"boost-version":"1.62.0",
"build-date":"2018-01-2519:30:05",
"build-repository":"heads/3.3.3-0-gd1ca58310e-dirty",
"compiler":"gcc[7.2.0]",
"cplusplus":"201103",
"debug":"false",
"endianness":"little",
"failure-tests":"false",
"fd-client-event-handler":"poll",
"fd-setsize":"1024",
"full-version-string":"ArangoDB3.3.3[linux]64bitmaintainermode,usingjemalloc,VPack0.1.30,RocksDB5.6.0,ICU58.
1,V85.7.492.77,OpenSSL1.0.2g1Mar2016",
"icu-version":"58.1",
"jemalloc":"true",
"maintainer-mode":"true",
"openssl-version":"OpenSSL1.0.2g1Mar2016",
"platform":"linux",
"reactor-type":"epoll",
"rocksdb-version":"5.6.0",
"server-version":"3.3.3",
"sizeofint":"4",
"sizeofvoid*":"8",
"sse42":"false",
"unaligned-access":"true",
"v8-version":"5.7.492.77",
"vpack-version":"0.1.30",
"zlib-version":"1.2.11",
"mode":"server",
"host":"c54ebb83e5eb4257b9e0f7201ba87ded"
}
}
ReturnCodes
200:isreturnedinallcases.
ResponseBody
version:theserverversionstring.Thestringhastheformat"major.minor.sub".majorandminorwillbenumeric,andsubmaycontainanumberoratextualversion.details:anoptionalJSONobjectwithadditionaldetails.Thisisreturnedonlyifthedetailsqueryparameterissettotrueintherequest.server:willalwayscontainarango
shell>curl--dump-http://localhost:8529/_api/version
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebodyReturntheversioninformationwithdetails
shell>curl--dump-http://localhost:8529/_api/version?details=true
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
Miscellaneousfunctions
409
showresponsebody
Returnserverdatabaseenginetype
returnstheenginethetypetheserverisrunningwith
GET/_api/engine
Returnsthestorageenginetheserverisconfiguredtouse.TheresponseisaJSONobjectwiththefollowingattributes:
AjsondocumentwiththesePropertiesisreturned:
HTTP200
isreturnedinallcases.
name:willbemmfilesorrocksdb
Example:Returntheactivestorageengine
shell>curl--dump-http://localhost:8529/_api/engine
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"name":"mmfiles",
"supports":{
"dfdb":true,
"indexes":[
"primary",
"edge",
"hash",
"skiplist",
"persistent",
"geo",
"fulltext"
]
}
}
ReturnCodes
200:isreturnedinallcases.
ResponseBody
name:willbemmfilesorrocksdb
shell>curl--dump-http://localhost:8529/_api/engine
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
showresponsebody
Flushesthewrite-aheadlog
Miscellaneousfunctions
410
SynctheWALtodisk.
PUT/_admin/wal/flush
PathParameters
waitForSync(optional):Whetherornottheoperationshouldblockuntilthenot-yetsynchronizeddatainthewrite-aheadlogwassynchronizedtodisk.waitForCollector(optional):Whetherornottheoperationshouldblockuntilthedataintheflushedloghasbeencollectedbythewrite-aheadloggarbagecollector.Notethatsettingthisoptiontotruemightblockforalongtimeiftherearelong-runningtransactionsandthewrite-aheadloggarbagecollectorcannotfinishgarbagecollection.
Flushesthewrite-aheadlog.Byflushingthecurrentlyactivewrite-aheadlogfile,thedatainitcanbetransferredtocollectionjournalsanddatafiles.Thisisusefultoensurethatalldataforacollectionispresentinthecollectionjournalsanddatafiles,forexample,whendumpingthedataofacollection.
ReturnCodes
200:Isreturnediftheoperationsucceeds.405:isreturnedwhenaninvalidHTTPmethodisused.
Retrievestheconfigurationofthewrite-aheadlog
fetchthecurrentconfiguration.
GET/_admin/wal/properties
Retrievestheconfigurationofthewrite-aheadlog.TheresultisaJSONobjectwiththefollowingattributes:
allowOversizeEntries:whetherornotoperationsthatarebiggerthanasinglelogfilecanbeexecutedandstoredlogfileSize:thesizeofeachwrite-aheadlogfilehistoricLogfiles:themaximumnumberofhistoriclogfilestokeepreserveLogfiles:themaximumnumberofreservelogfilesthatArangoDBallocatesinthebackgroundsyncInterval:theintervalforautomaticsynchronizationofnot-yetsynchronizedwrite-aheadlogdata(inmilliseconds)throttleWait:themaximumwaittimethatoperationswillwaitbeforetheygetabortedifcaseofwrite-throttling(inmilliseconds)throttleWhenPending:thenumberofunprocessedgarbage-collectionoperationsthat,whenreached,willactivatewrite-throttling.Avalueof0meansthatwrite-throttlingwillnotbetriggered.
Example:
shell>curl--dump-http://localhost:8529/_admin/wal/properties
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"allowOversizeEntries":true,
"logfileSize":33554432,
"historicLogfiles":10,
"reserveLogfiles":3,
"syncInterval":100,
"throttleWait":15000,
"throttleWhenPending":0
}
ReturnCodes
200:Isreturnediftheoperationsucceeds.405:isreturnedwhenaninvalidHTTPmethodisused.
Configuresthewrite-aheadlog
configureparametersofthewal
Miscellaneousfunctions
411
PUT/_admin/wal/properties
Configuresthebehaviorofthewrite-aheadlog.ThebodyoftherequestmustbeaJSONobjectwiththefollowingattributes:
allowOversizeEntries:whetherornotoperationsthatarebiggerthanasinglelogfilecanbeexecutedandstoredlogfileSize:thesizeofeachwrite-aheadlogfilehistoricLogfiles:themaximumnumberofhistoriclogfilestokeepreserveLogfiles:themaximumnumberofreservelogfilesthatArangoDBallocatesinthebackgroundthrottleWait:themaximumwaittimethatoperationswillwaitbeforetheygetabortedifcaseofwrite-throttling(inmilliseconds)throttleWhenPending:thenumberofunprocessedgarbage-collectionoperationsthat,whenreached,willactivatewrite-throttling.Avalueof0meansthatwrite-throttlingwillnotbetriggered.
Specifyinganyoftheaboveattributesisoptional.Notspecifiedattributeswillbeignoredandtheconfigurationforthemwillnotbemodified.
Example:
shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_admin/wal/properties<<EOF
{
"logfileSize":33554432,
"allowOversizeEntries":true
}
EOF
HTTP/1.1200OK
content-type:application/json;charset=utf-8
x-content-type-options:nosniff
{
"allowOversizeEntries":true,
"logfileSize":33554432,
"historicLogfiles":10,
"reserveLogfiles":3,
"syncInterval":100,
"throttleWait":15000,
"throttleWhenPending":0
}
ReturnCodes
200:Isreturnediftheoperationsucceeds.405:isreturnedwhenaninvalidHTTPmethodisused.
Returnsinformationaboutthecurrentlyrunningtransactions
returnsinformationaboutthecurrentlyrunningtransactions
GET/_admin/wal/transactions
Returnsinformationaboutthecurrentlyrunningtransactions.TheresultisaJSONobjectwiththefollowingattributes:
runningTransactions:numberofcurrentlyrunningtransactionsminLastCollected:minimumidofthelastcollectedlogfile(atthestartofeachrunningtransaction).Thisisnullifnotransactionisrunning.minLastSealed:minimumidofthelastsealedlogfile(atthestartofeachrunningtransaction).Thisisnullifnotransactionisrunning.
Example:
shell>curl--dump-http://localhost:8529/_admin/wal/transactions
HTTP/1.1200OK
content-type:application/json;charset=utf-8
Miscellaneousfunctions
412
x-content-type-options:nosniff
{
"runningTransactions":5,
"minLastCollected":85,
"minLastSealed":null
}
ReturnCodes
200:Isreturnediftheoperationsucceeds.405:isreturnedwhenaninvalidHTTPmethodisused.
Returnsystemtime
Getthecurrenttimeofthesystem
GET/_admin/time
Thecallreturnsanobjectwiththeattributetime.ThiscontainsthecurrentsystemtimeasaUnixtimestampwithmicrosecondprecision.
ReturnCodes
200:Timewasreturnedsuccessfully.
Returncurrentrequest
Sendbackwhatwassentin,headers,postbodyetc.
GET/_admin/echo
Thecallreturnsanobjectwiththefollowingattributes:
headers:objectwithHTTPheadersreceived
requestType:theHTTPrequestmethod(e.g.GET)
parameters:objectwithqueryparametersreceived
ReturnCodes
200:Echowasreturnedsuccessfully.
Returncurrentrequestandcontinues
Sendbackwhatwassentin,headers,postbodyetc.
GET/_admin/long_echo
Thecallreturnsanobjectwiththefollowingattributes:
headers:objectwithHTTPheadersreceived
requestType:theHTTPrequestmethod(e.g.GET)
parameters:objectwithqueryparametersreceived
ReturnCodes
200:Echowasreturnedsuccessfully.
Returntherequiredversionofthedatabase
returnstheversionofthedatabase.
GET/_admin/database/target-version
Returnsthedatabase-versionthatthisserverrequires.Theversionisreturnedintheversionattributeoftheresult.
ReturnCodes
Miscellaneousfunctions
413
200:Isreturnedinallcases.
Initiateshutdownsequence
initiatestheshutdownsequence
DELETE/_admin/shutdown
Thiscallinitiatesacleanshutdownsequence.Requiresadministriveprivileges
ReturnCodes
200:isreturnedinallcases.
Runstestsonserver
showtheavailableunittestsontheserver.
POST/_admin/test
RequestBody(required)
AJSONobjectcontaininganattributetestswhichliststhefilescontainingthetestsuites.
Executesthespecifiedtestsontheserverandreturnsanobjectwiththetestresults.Theobjecthasanattribute"error"whichstateswhetheranyerroroccurred.Theobjectalsohasanattribute"passed"whichindicateswhichtestspassedandwhichdidnot.
Executeprogram
Executeascriptontheserver.
POST/_admin/execute
RequestBody(required)
Thebodytobeexecuted.
Executesthejavascriptcodeinthebodyontheserverasthebodyofafunctionwithnoarguments.Ifyouhaveareturnstatementthenthereturnvalueyouproducewillbereturnedascontenttypeapplication/json.IftheparameterreturnAsJSONissettotrue,theresultwillbeaJSONobjectdescribingthereturnvaluedirectly,otherwiseastringproducedbyJSON.stringifywillbereturned.
NotethatthisAPIendpointwillonlybepresentiftheserverwasstartedwiththeoption--javascript.allow-admin-executetrue.
Thedefaultvalueofthisoptionisfalse,whichdisablestheexecutionofuser-definedcodeanddisablesthisAPIendpointentirely.Thisisalsotherecommendedsettingforproduction.
Miscellaneousfunctions
414
Top Related